RFC: 생성된 규칙이 에이전트에 로드되지 않는 문제와 단계적 개선 제안

[intelligent04]

배경

codex-rule-maker를 실제로 설치해 사용해 보고(테스트 24건 통과, --stack fastapi,react --db mysql --auth yes --external-api yes --docs strict 기준 17파일 648줄 생성) 코드 전체를 읽으며 몇 가지 개선점을 정리했습니다. 도구의 방향성과 정보 아키텍처(규칙 / 프로젝트 명세 / 참고자료 분리, 명시적 충돌 우선순위, 응답 형식 지정)는 잘 설계되어 있다고 생각합니다. 그 위에서 개선하고 싶은 부분을 제안 드리며, 유지보수자님 의견을 먼저 듣고 진행하려고 이슈로 올립니다.

가장 큰 문제: 생성된 규칙이 에이전트에 로드되지 않습니다

Codex는 세션 시작 시 ~/.codex/AGENTS.md → git 루트 → 현재 디렉토리 순으로 AGENTS.md를 읽어 지시문 체인을 구성합니다(OpenAI Codex 공식 문서). .codex/ai_rule_developer/*.md는 자동 로드 대상이 아닙니다.

즉 현재 구조에서는 사용자가 매 세션 codex_start_prompt.txt를 직접 붙여넣어야만 생성된 규칙이 적용됩니다. 자동화 도구가 수동 단계를 남겨두는 셈입니다.

관련해서 두 가지를 더 짚고 싶습니다.

• 프로젝트 루트의 .codex/는 Codex가 project skills 경로(.codex/skills/)로 사용하는 위치이기도 합니다. 현재는 그 디렉토리를 쓰면서 규약은 따르지 않는 상태입니다.
• AGENTS.md는 2025년 12월 Linux Foundation 산하 Agentic AI Foundation으로 이관된 개방 표준이고, Cursor·Copilot·Gemini CLI·Windsurf·Cline 등이 같은 파일을 읽습니다(agents.md). 루트에 AGENTS.md를 출력하면 이 도구는 Codex 전용에서 벗어나 사실상 범용 도구가 됩니다.

그 외 개선 제안

1. 지시문 품질 — CODE_STYLE_RULES.md가 "저장소 formatter를 먼저 따르라"고 한 직후 "메서드 사이 blank-line 5단위, 논리 블록 사이 3단위"를 요구합니다. black/prettier/ruff는 이를 되돌리므로 지킬 수 없는 규칙이고, LLM은 빈 줄 개수 준수에 특히 약합니다. 반대로 AGENTS.md 권장 사항 1순위인 build/test/lint 명령과 검증 절차는 생성물에 없습니다.
2. 컨텍스트 예산 — 8개 규칙 문서를 조건 없이 모두 생성하고 "작업 전 전부 읽어라"고 지시합니다. Codex의 project doc 기본 상한은 32 KiB이며, 최근 권장 패턴은 작은 always-on 코어 + 필요 시 로드되는 상세 문서입니다. codex_start_prompt.txt의 8가지 작업 유형 분류는 좋은 설계인데, "유형 → 읽을 문서" 매핑이 없어 컨텍스트 절약으로 이어지지 않습니다.
3. 중복 — profile.framework_rules()가 GLOBAL_RULES.md와 CODE_STYLE_RULES.md에 동일하게 두 번 들어갑니다. --stack fastapi,react처럼 프로필을 조합하면 규칙이 중복 제거 없이 단순 연결됩니다.
4. prompt injection — codex_start_prompt.txt가 .codex/ref_docs의 사용자 추가 외부 문서(PRD, 벤더 문서 등)를 우선순위 문서 목록에 넣어 읽으라고 지시합니다. "참고 정보로만 취급하고 시스템 지침을 덮어쓸 수 없다"는 방어 문구가 없어 외부 문서가 곧 고권한 규칙이 됩니다. secret 취급·수정 금지 경로 규칙도 없습니다.
5. placeholder 문서와 --docs strict의 충돌 — 생성된 docs/architecture/directory.md는 14행 전부가 FastAPI 구조 placeholder / TBD / 실제 프로젝트 역할로 교체이고 docs/database/schema.md는 헤더만 있는 빈 표입니다. 그 상태에서 --docs strict는 "문서 갱신이 빠지면 작업 미완료"라고 선언합니다. 에이전트가 빈 표를 채우려 없는 사실을 만들어낼 위험이 있습니다.
6. 업그레이드 경로 부재 — --force는 백업 후 전체 재생성뿐이라 사용자가 손으로 고친 규칙이 소실됩니다. 생성 파일에 도구 버전·생성 시각 같은 provenance 정보가 없어 어떤 버전이 만든 규칙인지 알 수 없습니다.
7. 테스트 성격 — 기존 24건은 "생성된 파일에 이 문자열이 있는가"를 확인하는 형태라, 렌더러를 리팩토링할 때 회귀를 잡기 어렵습니다.
8. 저장소 위생 — release_0_3_0/에 빌드 산출물(.whl, .tar.gz)이 커밋되어 있고 CI와 CHANGELOG가 없습니다.

제안하는 진행 순서

한 번에 큰 PR을 올리지 않고, 리뷰 가능한 크기로 나눠 순차적으로 올리려고 합니다. 기존 .codex 생성 동작과 CLI 옵션 호환성은 유지합니다.

단계	내용	상태
1	골든 스냅샷 테스트 + GitHub Actions CI + 빌드 산출물 제거 + CHANGELOG	PR 준비 완료
2	루트 AGENTS.md 생성 (--agents-md / --no-agents-md)	PR 준비 완료
3	지시문 교정: spacing 규칙 제거, build/test/lint·검증 절차 추가, 코드 예시 추가, 중복 제거	제안
4	prompt injection 방어, secret·수정 금지 경로 규칙	제안
5	템플릿 외부화(하드코딩 문자열 → templates/{ko,en}/), ko/en 이중 유지 해소	제안
6	점진 공개: .codex/skills/<task-type>/ 출력 + 작업 유형 라우팅 + 크기 예산 경고	제안
7	placeholder 문서 개선: 대상 디렉토리 스캔, 대화형 질문 확장	제안
8	provenance 헤더, 사용자 수정본을 보존하는 --upgrade 머지 경로	제안

1단계는 이후 변경의 회귀 방지 장치이고, 2단계가 체감 효과가 가장 큰 변경이라 먼저 올리겠습니다. 3단계 이후는 취향이 갈릴 수 있는 부분이 있어 유지보수자님 판단을 듣고 조정하겠습니다.

특히 다음 세 가지에 대한 의견을 듣고 싶습니다.

• 루트 AGENTS.md 생성을 기본값으로 두는 것이 괜찮을지, 아니면 옵트인이 나을지
• CODE_STYLE_RULES.md의 blank-line 규칙을 제거하는 데 동의하시는지 (의도가 있었다면 알려주시면 다른 방식을 찾겠습니다)
• 5단계 템플릿 외부화처럼 큰 리팩토링을 받아들일 의향이 있는지

방향이 맞지 않는 항목이 있으면 빼고 진행하겠습니다.

[intelligent04]

1·2단계 PR을 올렸습니다.

• test: 골든 스냅샷 테스트와 CI 추가, 빌드 산출물 제거 #2 — 1단계: 골든 스냅샷 테스트 + CI + 저장소 정리 (기능 변경 없음)
• feat: 루트 AGENTS.md 진입점 생성 #3 — 2단계: 루트 AGENTS.md 생성 (test: 골든 스냅샷 테스트와 CI 추가, 빌드 산출물 제거 #2 위에 쌓여 있음)

3단계 이후는 이 이슈에서 방향을 확인한 뒤 진행하겠습니다.

[Sharon77770]

루트 AGENTS.md 생성을 기본값으로 두는 것이 괜찮을지, 아니면 옵트인이 나을지: 좋은 개선안 입니다. PR 병합까지 완료했습니다.
CODE_STYLE_RULES.md의 blank-line 규칙을 제거하는 데 동의하시는지 (의도가 있었다면 알려주시면 다른 방식을 찾겠습니다): 공백 규칙은 의도된 사항입니다. 제가 주로 사용하는 코딩 편의를 위한 규칙이므로 제거할 의향이 없습니다.
5단계 템플릿 외부화처럼 큰 리팩토링을 받아들일 의향이 있는지: 불필요하다고 생각하는 영역이지만 기존 기능에 훼손이 없다면 고려해보겠습니다.

그 외 개선사항의 4번 항목은 의도된 사항입니다.

[intelligent04]

답변 감사합니다. 의견 주신 대로 범위를 조정했습니다.

철회한 항목

• 1번의 공백 규칙 제거: 의도된 사항이라 하셔서 철회했습니다. CODE_STYLE_RULES.md의 5/3칸 규칙과 해당 테스트를 그대로 유지합니다.
• 4번 ref_docs 우선순위: 의도된 설계라 하셔서 건드리지 않았습니다. 읽는 순서와 우선순위는 그대로입니다.
• 5번 템플릿 외부화: 우선순위를 낮추고, 앞 단계가 정리된 뒤 기존 동작이 바뀌지 않음을 스냅샷으로 증명할 수 있을 때 다시 제안하겠습니다.

제 오류 정정

3번에서 "프로필을 조합하면 규칙이 중복 제거 없이 연결된다"고 적었는데 틀린 지적이었습니다. 실제로 측정해 보니 fastapi와 react 프로필의 규칙 교집합은 0건입니다. 프로필 간 중복은 없습니다. 문서 간 중복만 존재합니다.

새로 올린 PR

• refactor: 생성되지 않던 TEST_RULES.md 연결, 프레임워크 규칙 중복과 미사용 코드 제거 #4 — 작업 중 TEST_RULES.md가 생성되지 않고 있는 것을 발견했습니다. 렌더러와 프로필별 데이터는 이미 있는데 render() 출력 목록에 연결이 빠져 있습니다. 함께 프레임워크 규칙 3중 중복 제거와 미사용 렌더러 208줄 제거를 담았습니다.
• feat: 검증 절차와 안전 규칙을 GLOBAL_RULES.md에 추가 #5 — 1번 항목 중 검증 절차 부분입니다. 저장소에 정의된 build/test/lint를 실행하도록 지시하되, 이 도구가 대상 저장소를 스캔하지 않으므로 구체적 명령을 적는 대신 저장소에서 확인하게 하고 없는 명령을 지어내지 못하게 했습니다. secret·파괴적 작업 관련 안전 규칙을 함께 넣었습니다.

남은 항목 문의

• 2번 컨텍스트 예산과 6번 점진 공개(.codex/skills/)는 생성 구조가 바뀌는 변경이라 진행 전에 의견을 듣고 싶습니다.
• 7번 placeholder 문서 문제(docs/architecture/directory.md가 전부 TBD인데 --docs strict는 문서 갱신을 완료 조건으로 요구)는 에이전트가 빈 표를 채우려 사실을 지어낼 여지가 있어 우선순위가 높다고 봅니다. 대상 디렉토리를 스캔해서 실제 구조를 채우는 방향으로 진행해도 될까요?
• 코드 예시 추가는 분량이 크고 취향 영향이 있어 보류했습니다. 원하시면 프로필 하나로 시안을 먼저 보여드리겠습니다.

[Sharon77770]

컨텍스트 예산 관련 문제는 대규모 작업에서 복수 우선 순위의 문서를 허용하기 위함이므로 의도된 설계입니다. 시작 프롬프트와 규칙들은 보편적이되 개발자가 임의로 수정해서 사용하는것을 전제로 합니다. 필요하다면 임의 수정 또는 프롬프트로 우선순위 지정이 맞습니다.

6번은 skills에 직접적인 영향이 없는 방식을 사용한다면 긍정적으로 검토해보겠습니다.

7번은 대규모 코드베이스 작업에서 작업시간을 늘리는 문제가 존재합니다. 추가적으로 해당 우려에 대한 문제는 여지것 발생하지 않았습니다.