AGENTS.md vs 컨텍스트

잘못하고 있는 건 아니지만, 파일이 계속 커지기만 한다면 Codex 문서에서 확인해 볼 만한 구체적인 제한 사항이 하나 있습니다.

Codex는 빈 파일을 건너뛰고, 결합된 크기가 project_doc_max_bytes(기본값 32KiB)에 도달하면 파일 추가를 중단합니다.

같은 페이지의 문제 해결 목록에는 "지침이 잘림: project_doc_max_bytes를 높이거나 큰 파일을 중첩된 디렉토리로 분할하여 중요한 지침을 유지하세요"라고 되어 있습니다. 따라서 AGENTS.md(및 ~/.codex의 전역 파일과 중첩된 파일들)가 제한을 넘었다면, 새로 추가한 교훈들이 모델에 전달되지 않을 수 있습니다. 그러면 "예전엔 잘 배웠는데 이제는 실수를 반복하네" 같은 현상이 나타날 겁니다.

문서에서 할 수 있는 두 가지 방법:

• 크기를 확인하세요. 예: wc -c AGENTS.md ~/.codex/AGENTS.md를 입력하고 경로상의 모든 중첩 파일과 합산하세요.

• 제한에 가깝다면 config.toml에서 제한을 높이거나(문서 예시는 project_doc_max_bytes = 65536), 디렉토리별 규칙을 중첩된 AGENTS.md 파일로 옮기세요. 작업 디렉토리에 가까운 파일이 "결합된 프롬프트에서 나중에 나타나기" 때문에 충돌 시 우선순위를 갖습니다.

위에서 언급한 스킬 제안이 나머지 절반입니다. 문서에는 나와 있지 않지만, 규칙 그룹을 필요할 때만 로드하면 매 턴마다 컨텍스트를 사용하지 않게 될 겁니다. 얼마나 절약되는지는 측정해보지 않았습니다.

그렇게 크지 않다면 괜찮지만, 제 생각엔 작성자님 파일은 좀 클 것 같네요. 또 고려해야 할 점은 에이전트가 실행 시작 시점에 읽고 나면 최근에 일어난 일에 집중하는 경향이 있다는 겁니다. 압축(compaction)이 일어날 때 Claude가 agents와 Claude.md를 다시 컨텍스트에 넣는 건 알지만, Codex에 대해서는 명확한 정보를 얻지 못했습니다. 하지만 아마 비슷할 겁니다. 그래서 긴 실행의 끝부분, 압축 직전에는 에이전트가 잊어버리거나 agents.md에 덜 주의를 기울일 가능성이 커집니다. 여기서 훅(hook)이 필요합니다. 에이전트가 특정 도구를 사용하지 않거나 종료 절차를 잊어버리는 등의 실수를 한다면, 훅은 턴의 시작, 중간, 끝에 주입되어 에이전트에게 무언가를 하라고 상기시키는 프롬프트입니다.

그러니 agents.md 방식이 잘 작동한다면 괜찮지만, 에이전트에게 직접 검토를 요청해보세요. 더 긴 지침은 다른 파일에 넣고 agents.md는 그 파일을 링크하게 만들 수 있을 겁니다. 그러면 불필요한 컨텍스트가 에이전트 창에 들어가지 않아 가끔씩만 하는 작업에 대한 지침을 계속 들고 다닐 필요가 없죠. 다른 파일에 대한 포인터는 트리거를 유지할 수 있게 해주면서, 긴 지침은 다른 곳에 두었다가 트리거가 발생할 때만 해당 파일을 보게 하니까 좋습니다.

도움이 되었길 바랍니다. 솔직히 궁금한 게 있으면 에이전트에게 직접 물어보세요. 그들은 기꺼이 설명해 줄 겁니다. 하루 종일 명령만 내릴 필요 없어요, 질문해도 괜찮습니다 😝

"컨텍스트"는 별개의 무언가가 아닙니다.

입력하는 텍스트가 전부입니다. Codex는 그저 매번 수동으로 텍스트를 붙여넣는 과정을 자동화할 뿐입니다.

저는 Open Brain 무료 버전을 사용해서 그렇게 합니다. 모든 관리 문서, 설계 결정, 테스트, 디버깅 결과가 거기로 들어갑니다. 프로젝트의 모든 변경 사항도요. 저는 모든 것을 2가지 카테고리로 분류하는데, 30일 후 자동 소프트 삭제되고 45일 후 영구 삭제됩니다. 덕분에 중간 결과물과 비분류 데이터를 자동으로 비공개 처리할 수 있습니다. 소프트 삭제를 통해 자동 분류를 깜빡했을 때 복구하고 비공개 처리할 수 있죠. Codex가 제 사양을 사용해서 관리 콘솔을 작성해 줬습니다. Open Brain은 이런 유형의 애플리케이션들처럼 소프트 삭제 기능이 없어서, Postgres 데이터베이스에 테이블 2개를 추가로 만들었습니다. Codex와 ChatGPT Work는 모든 이벤트를 자동으로 기록합니다.

잘못된 거 아닙니다. 저도 비슷하게 하지만 모든 교훈을 AGENTS.md에 넣지는 않습니다. 스크립트로 확인할 수 있는 교훈은 규칙 이름과 같은 이름의 테스트가 됩니다. 지금 86개의 테스트가 있습니다. AGENTS.md는 규칙을 한 번 명시하고, 테스트는 모델이 주의 깊게 읽지 않았을 때도 규칙이 유지되도록 보장합니다.

크기에 관해서는, 제 AGENTS.md는 19KB입니다. kuroudo가 말했듯이 Codex는 제한 이후의 내용을 조용히 잘라버리기 때문에, 저는 project_doc_max_bytes를 64KB로 올렸고 파일이 그보다 커지면 테스트가 실패하게 했습니다. 테스트가 없으면 예전 교훈들이 작동을 멈출 때만 알아차릴 수 있죠.

사양과 절차는 AGENTS.md에 전혀 없습니다. 스크립트가 빌드할 때마다 줄 번호가 포함된 모든 사양의 인덱스를 생성하고, 에이전트는 필요한 섹션만 읽습니다. 메모리는 꺼져 있어서 규칙은 git에서 볼 수 있는 파일에만 존재합니다.

각 섹션 상단에 누가 그 섹션을 읽어야 하는지 적어두면 대부분의 에이전트가 대부분의 부분을 건너뛸 겁니다. 제 루트 AGENTS.md의 대부분은 상태 머신처럼 작성되어 있는데 아주 잘 작동합니다. 또한 에이전트가 너무 성급하게 행동하는 것들에 대해 하지 말아야 할 일을 적거나 권한 게이트를 추가하기에 더 좋은 장소라는 걸 알게 됐습니다. 예를 들어 어제 제 서브 에이전트가 제가 X 게시물을 문서에 임베드하려고 할 때 사이트를 만들려고 하길래, 사이트를 만들기 전에 항상 사용자 승인을 받으라는 권한 게이트를 추가했습니다.