AGENTS.md 자동 업데이트: dox 활용법

3주 뒤에 AGENTS.md 파일이 잘못되는 이유

AGENTS.md 파일은 코드와 연결된 부분이 없기 때문에 시간이 지나면 쓸모없어집니다. 저장소의 상태가 특정 시점일 때 수동으로 한 번 작성해 두면, 이후 테스트 러너가 변경되거나 패키지 이름이 바뀌거나 서비스가 삭제되어도 파일은 여전히 6월의 상태를 설명하고 있습니다. 빌드 단계에서 이 파일을 읽지 않으므로 아무런 오류도 발생하지 않습니다.

에이전트는 이 파일을 읽고 그대로 믿습니다. 바로 이 지점이 비용을 발생시킵니다. AGENTS.md 파일이 없는 저장소에서는 코딩 에이전트가 작업을 수행하기 전에 주변을 살핍니다. 반면 잘못된 AGENTS.md 파일이 있는 저장소에서는 에이전트가 이미 답을 알고 있다고 판단하여 확인을 멈춥니다. 에이전트는 파일에 적힌 명령어를 실행하고, 셸은 Missing script: "test"라고 응답하며, 이때부터 에이전트는 추측을 시작합니다. 종종 에이전트는 문서가 약속했던 스크립트를 추가하기 위해 package.json을 편집하기도 합니다. 오래된 파일은 조용히 실패하지 않았습니다. 원치 않는 편집을 유발한 것입니다.

dox는 이에 대한 하나의 해결책입니다. 이는 에이전트를 위해 작성된 규칙 집합으로, 문서 업데이트를 작업 완료의 일부로 만듭니다. 따라서 파일은 해당 변경을 유발한 코드와 동일한 커밋에서 수정됩니다.

dox의 정의와 비정의

dox는 단일 Markdown 파일입니다. 저장소는 agent0ai/dox이며 MIT 라이선스를 따릅니다. 2026년 8월 11일 기준으로 전체 프로젝트는 3906바이트 크기의 AGENTS.md 파일 하나와 README, LICENSE, 이미지 2개로 구성됩니다. 설치할 패키지나 런타임은 존재하지 않습니다.

이 점이 중요한 이유는 '생성기(generator)'라는 단어가 코드를 파싱하는 프로그램을 연상시키기 때문입니다. dox는 코드를 파싱하지 않습니다. dox는 코딩 에이전트가 읽는 계약서입니다. 에이전트가 곧 생성기이며, dox는 에이전트에게 언제 문서를 읽고, 언제 다시 작성하며, 각 문서가 어떤 형태를 갖춰야 하는지 지시하는 명령어 세트입니다.

이 파일은 10개의 섹션으로 구성되며, 그중 2개가 핵심적인 역할을 수행합니다. "편집 전 읽기(Read Before Editing)"는 에이전트에게 저장소 루트에서 수정하려는 모든 경로까지 이동하며, 메모리에 의존하지 말고 현재 세션 내에서 경로상의 모든 AGENTS.md를 읽도록 지시합니다. "편집 후 업데이트(Update After Editing)"는 의미 있는 모든 변경 사항에는 DOX 패스가 필요함을 명시합니다. 즉, 작업이 완료된 것으로 간주되기 전에 문서 업데이트 단계를 실행해야 한다는 뜻입니다. 이 패스는 목적, 구조, 워크플로, 권한 또는 사용자 설정이 변경되었을 때 가장 가까운 소유 문서를 업데이트합니다.

나머지 섹션은 문서의 형태를 정의합니다. 하위 AGENTS.md는 기본 섹션 순서인 목적(Purpose), 소유권(Ownership), 로컬 계약(Local Contracts), 작업 지침(Work Guidance), 검증(Verification), 하위 DOX 인덱스(Child DOX Index)를 따릅니다. 루트 파일은 프로젝트 전반의 규칙과 최상위 하위 DOX 인덱스를 담고 있으며, 에이전트는 이를 통해 하위 문서를 발견합니다. "마무리(Closeout)"는 작업 종료 시 에이전트가 실행하는 체크리스트입니다. 변경된 경로를 체인에 따라 재확인하고, 가장 가까운 소유 문서를 업데이트하며, 영향을 받는 모든 인덱스를 새로 고치고, 모순되는 내용을 삭제하며, 기존 검증을 실행하고, 의도적으로 수정하지 않은 문서를 보고합니다.

문서(dox)를 main이 아닌 특정 커밋에 고정하기

저장소에 태그나 릴리스가 없으므로 고정할 버전 번호가 없습니다. 대신 커밋을 고정하십시오. 현재 AGENTS.md는 2026년 8월 1일 자 커밋 f34ec7ad1055d3393887e5a2670e8cb7320c9165입니다.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c는 3906를 출력해야 합니다. 다른 숫자가 나온다면 이 가이드가 설명하는 파일을 가져오지 않은 것이므로, 신뢰하기 전에 다시 읽어보십시오. 커밋 해시를 잘못 입력하면 -f은 curl: (22) The requested URL returned error: 404과 함께 curl을 중단시키고 내용을 기록하지 않으며, wc -c은 0를 출력합니다. 잘린 파일은 파일이 없는 것보다 더 위험합니다. 에이전트가 계약의 절반만 알고 따르게 되기 때문입니다.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

그 cp은 아직 AGENTS.md가 없는 저장소를 위한 것입니다. 이미 파일이 있다면 덮어쓰지 마십시오. 기존 내용 아래에 본인만의 규칙을 유지하고, dox 섹션을 그 위에 배치한 뒤 처음부터 끝까지 한 번 읽어보십시오. 서로 모순되는 두 문서는 마지막에 읽은 줄을 따르는 에이전트를 만듭니다.

그런 다음 저장소 내부에서 에이전트에게 첫 번째 패스를 요청하십시오. README에 정확한 문구가 나와 있습니다.

Initialize DOX tree for this project now.

이 명령은 하위 AGENTS.md 파일들과 그것을 가리키는 인덱스를 생성합니다. 결과를 믿기 전에 수행된 작업을 확인하십시오.

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

find 출력에 나타나는 모든 파일은 어딘가 상위에 있는 하위 DOX 인덱스(Child DOX Index)에 명시되어야 합니다. 인덱스에 언급되지 않은 하위 문서는 에이전트가 놓칠 수 있습니다. 인덱스는 에이전트가 현재 경로에 직접 위치하지 않는 문서를 찾는 방법이기 때문입니다.

dox가 볼 수 있는 것과 알 수 없는 것

트리를 빌드하는 에이전트는 저장소를 읽으므로, 저장소에 있는 모든 내용은 인벤토리에 포함될 수 있습니다. 디렉터리 구조, 패키지 매니페스트 및 락파일, package.json나 Makefile 또는 pyproject.toml의 스크립트, CI 워크플로우 파일, Dockerfile, 진입점, 그리고 존재하는 경우 CODEOWNERS까지 포함됩니다. 이들로부터 생성된 인벤토리는 진정한 의미에서 스스로 유지 관리됩니다. 패키지가 이동하면 다음 패스에서 해당 패키지를 설명하는 줄도 함께 이동합니다.

아래 내용은 저장소에 읽을 수 있는 형태로 존재하지 않으므로 사용자가 직접 명시해야 합니다:

• 규칙이 존재하는 이유: 에이전트가 이를 불필요한 복잡성으로 간주하여 제거하는 것을 방지합니다.
• 두 가지 작업 경로 중 지원되는 것과 삭제 대기 중인 것.
• 스테이징 환경이나 의존성을 두 버전 이전으로 고정한 이유와 같이 저장소 외부에 있는 모든 정보.
• 다음 주에 수행할 계획: 이는 현재 상태인 파일과 유용한 파일의 차이를 결정합니다.

dox는 스스로에 대해 이러한 점을 알고 있습니다. dox의 자체 규칙에 따르면 작업 지침(Work Guidance)은 프로젝트의 현재 표준이나 사용자의 지침을 반영해야 하며, 아직 아무것도 없다면 해당 섹션을 비워 두어야 합니다. 검증(Verification)은 기존의 체크를 반영해야 하므로, 저장소에 테스트 프레임워크가 없다면 해당 섹션은 테스트 프레임워크가 생길 때까지 비어 있게 됩니다. 표준을 임의로 만들어내는 생성된 파일은 비어 있는 섹션보다 나쁩니다. 에이전트가 그 임의의 표준을 강제하게 되기 때문입니다.

생성된 인벤토리에서 수동으로 작성한 의도를 분리하십시오

이것은 사람들이 자동 생성된 문서 사용을 포기하게 만드는 실패 사례입니다. 작업 큐(jobs queue)는 단일 소비자(single consumer)로 유지되어야 한다는 설명을 단락으로 작성했다고 가정해 봅시다. 3주 후, 자동화 도구가 파일을 다시 작성하면서 해당 단락이 사라집니다. 파일 이름이 변경된 40줄짜리 diff 속에서 이 변경 사항을 알아차리는 사람은 아무도 없습니다.

두 가지 메커니즘을 모두 활용해야 합니다.

첫째, 지속적인 의도는 별도의 파일로 옮기십시오. 설계 결정 사항과 그 근거는 에이전트를 위한 DESIGN.md에 작성해야 하며, 사람을 위한 메모는 HUMAN.md와 AGENTS.md를 분리하여 관리해야 합니다. AGENTS.md는 인벤토리와 로컬 계약(local contracts)을 담게 되며, 이는 코드 변경 시 정확히 수정되어야 할 부분입니다.

둘째, AGENTS.md 내부에 유지해야 하는 의도에는 울타리를 치십시오. 마커로 해당 블록을 감싸고 사람이 소유한 영역으로 취급하십시오:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown 주석은 페이지에 렌더링되지 않으며, 에이전트는 여전히 이를 읽을 수 있습니다. 이제 해당 블록이 유지되는지 확인할 수 있도록 만드십시오. 블록을 삭제하는 자동화 작업이 발생하면 큰 소리로 실패하게 만듭니다. 모든 pull request의 CI(지속적 통합)에서 다음을 실행하십시오:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff은 블록이 변경되지 않았을 때 아무것도 출력하지 않고 0을 반환합니다. 출력이 발생한다는 것은 자동화 도구가 사람이 소유한 텍스트를 다시 작성했다는 의미이므로, 담당자가 이를 승인하거나 되돌려야 합니다. 이 확인 절차는 아무도 기억할 필요 없이 시스템적으로 유지됩니다.

타이머가 아닌 풀 리퀘스트 시점에 재생성

문서를 갱신하기 가장 좋은 시점은 문서가 잘못된 내용을 담게 된 바로 그 커밋이 발생하는 때입니다. DOX 작업을 구조적 변경이 포함된 동일한 풀 리퀘스트에 포함하면, diff가 충분히 작게 유지되어 실제로 내용을 검토할 수 있습니다.

이를 강제하는 차단형 검사 설정입니다:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

저장소 경로에 맞게 수정하십시오. 이 방식의 가치는 브랜치 단계에서 실패를 유도하여 수정 비용을 낮추고, 리뷰어가 조치를 취할 수 있는 명확한 이유를 제공한다는 점입니다.

일정 기반 작업은 메커니즘이 아니라 백업 수단입니다. 주간 작업은 브랜치에서 아무도 눈치채지 못한 문제, 즉 리베이스로 이동한 파일, 병합 과정에서 삭제된 패키지, 더 이상 존재하지 않는 디렉터리를 가리키는 문서 등을 포착합니다. 이 작업은 VPS에서 코딩 에이전트 실행하기에 사용하는 것과 같은 소형 서버에서 실행하고, main 브랜치로 직접 푸시하는 대신 풀 리퀘스트를 생성하도록 설정하십시오.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

해당 주석은 의도적으로 비워둔 자리 표시자입니다. 모든 에이전트는 고유한 CLI(명령줄 인터페이스)와 비대화형 플래그를 가지고 있으며, 웹 페이지에서 복사한 명령어가 현재 버전과 일치하지 않으면 cron 내부에서 오류가 발생해도 아무도 알 수 없습니다. 내용을 채우고 스케줄에 등록하기 전에 반드시 수동으로 스크립트를 한 번 실행해 보십시오. || exit 0 또한 중요합니다. 트리가 이미 최신 상태일 때 git commit은 nothing to commit, working tree clean와 함께 0이 아닌 종료 코드를 반환하며, set -e 환경에서는 이를 정상적인 실행임에도 실패로 보고할 수 있습니다.

모든 작업은 토큰을 소모합니다. "편집 전 읽기(Read Before Editing)" 과정에서 에이전트가 각 작업마다 전체 체인을 읽어야 하기 때문입니다. 이것이 트레이드오프이며, 이미 에이전트 실행 비용을 계산하고 있다면 주의 깊게 살펴볼 가치가 있습니다.

모노레포: 다수의 계약, 하나의 인덱스

40개의 패키지가 포함된 저장소에 루트 AGENTS.md 파일 하나만 존재하면, 아무도 읽지 않는 재생성 diff가 발생하며, 현재 에이전트가 수행 중인 작업과는 무관한 문서가 생성됩니다. 이에 대한 dox의 해결책은 하위 DOX 인덱스(Child DOX Index)입니다. 루트에는 저장소 전체에 적용되는 규칙을 담고 하위 항목을 가리키도록 하며, 각 경계(boundary)마다 고유한 파일을 소유하게 합니다. 이러한 트리 구조를 구성하는 방법과 중첩된 파일을 읽을 수 있는 도구에 대해서는 모노레포를 위한 중첩 AGENTS.md 파일에서 다룹니다.

dox가 변경하는 것은 검토 범위입니다. packages/api을 수정하는 풀 리퀘스트는 packages/api 내부의 문서 diff만 생성해야 하며, 다른 곳은 건드리지 않아야 합니다.

git diff --stat -- '*AGENTS.md'

만약 해당 명령어가 단일 패키지 변경에 대해 6개의 파일을 나열한다면, 트리 구조가 잘못된 것입니다. 경계가 너무 포괄적이거나, 루트에 있어야 할 규칙이 모든 하위 항목에 복사된 경우입니다. dox는 이에 대한 해결책을 명확히 제시합니다. 광범위한 규칙은 상위 문서에, 구체적인 세부 사항은 하위 문서에 작성하십시오. 규칙이 중복되면 일상적인 변경 작업 시 모든 문서가 다시 작성되는 문제가 발생합니다. 만약 동일한 규칙이 서로 다른 저장소에 걸쳐 적용되어야 한다면, 이는 다른 문제이며 저장소 간 에이전트 기술 공유가 더 적합한 도구입니다.

코드처럼 diff 검토하기

생성된 문서의 diff는 읽지 않고 승인하기 쉬우며, 이로 인해 잘못된 파일이 릴리스됩니다. 생성된 코드를 검토할 때와 같은 의심을 가지고 다음 네 가지 사항을 확인하십시오.

• 파일에 명시된 명령어를 직접 실행해 보십시오. 병합하기 전에 직접 실행해야 합니다. 임의로 작성된 빌드 지침이 가장 흔한 실패 원인입니다.
• 의도가 담긴 삭제된 줄을 확인하십시오. 추가는 쉽습니다. 삭제된 부분에서 정보 손실이 발생합니다.
• 절대 경로, 호스트 이름, 내부 URL 또는 자격 증명처럼 보이는 모든 항목을 확인하십시오.
• 더 이상 존재하지 않는 항목에 대한 인벤토리 항목을 확인하십시오. 이는 ls에서 즉시 해결됩니다.

그런 다음 wc -l AGENTS.md를 사용하여 크기를 확인하십시오. 루트 파일이 200줄을 넘어가면 파일을 분할해야 한다는 신호입니다. 에이전트가 전체 내용을 읽는 대신 작고 관련 있는 부분만 읽는 것이 이 체인의 핵심 가치이기 때문입니다.

오류 발생 시

패스가 의도한 블록을 삭제했습니다. 위에서 수행한 diff 검사 결과에 삭제된 줄이 출력됩니다. git restore --source=origin/main AGENTS.md을 사용하여 브랜치 지점에서 파일을 복구한 뒤, 영향을 줄 수 있는 섹션을 명시하는 더 구체적인 지침으로 패스를 다시 실행하십시오.

두 브랜치가 모두 재생성되었습니다. 파일 내부에 CONFLICT (content): Merge conflict in AGENTS.md과 충돌 마커 <<<<<<< HEAD이 생성됩니다. 마커를 직접 수정하지 마십시오. 파일은 생성된 것이므로, 병합된 트리에서 패스를 새로 실행하는 것이 올바른 해결 방법입니다.

에이전트가 파일을 완전히 무시합니다. 도구가 실제로 읽고 있는 파일명을 확인하십시오. 다른 파일을 읽고 있다면 ln -s AGENTS.md CLAUDE.md를 사용하여 동일한 콘텐츠를 가리키도록 설정하고 심볼릭 링크를 커밋하십시오. 이렇게 하면 두 문서가 서로 달라지는 것을 방지하고 하나의 소스만 유지할 수 있습니다.

트리에 인덱싱되지 않은 하위 항목이 생겼습니다. find . -name AGENTS.md 출력 결과와 상위 문서의 인덱스 항목을 비교하십시오. 어떤 인덱스에도 언급되지 않은 하위 항목은 에이전트가 그냥 지나치게 됩니다.

제너레이터가 과도한 경우

패키지가 하나이고, 테스트 명령어가 하나이며, 저장소를 잘 아는 사람 두 명이 작업한다면 20줄 정도는 직접 작성하는 것이 좋습니다. 20줄짜리 AGENTS.md 파일은 트리 구조, 인덱스, CI 검사, 주간 작업 등을 도입할 만큼 빠르게 노후화되지 않습니다. 빌드를 변경할 때 파일을 다시 읽어보는 것이 유지보수 비용의 전부이며, 이는 자동화 도구를 구축하고 관리하는 비용보다 훨씬 적습니다.

dox와 같은 도구는 한 사람이 모든 경계를 파악할 수 없는 저장소일 때 가치가 있습니다. 서로 다른 규칙을 가진 여러 패키지가 있거나, 배경지식 없이 참여하는 기여자가 있는 경우가 이에 해당합니다. 도구의 가치는 생성된 텍스트 자체에 있지 않습니다. 문서화가 풀 리퀘스트의 통과 여부를 결정하는 기준이 된다는 점에 가치가 있으며, 이것이 저장소 내의 파일이 최신 상태로 유지되는 유일한 이유입니다.

FAQ

dox를 사용하려면 무엇을 설치해야 합니까?

아무것도 설치할 필요가 없습니다. dox는 MIT 라이선스를 따르는 단일 Markdown 파일이며, 2026년 8월 11일 기준으로 저장소에서 제공하는 패키지나 릴리스는 없습니다. 파일 내용을 프로젝트의 AGENTS.md에 복사하면 코딩 에이전트가 해당 규칙을 따릅니다. 복사한 커밋을 고정하고(작성 시점 기준 f34ec7ad1055d3393887e5a2670e8cb7320c9165), 커밋 메시지에 해당 커밋을 명시하여 나중에 어떤 버전의 규칙을 기반으로 트리가 빌드되었는지 확인할 수 있도록 하십시오.

재생성 시 직접 작성한 규칙이 삭제되지 않게 하려면 어떻게 해야 합니까?

의도와 인벤토리를 분리하십시오. 지속적인 추론은 별도의 문서에 작성하고, AGENTS.md 내부에 반드시 유지해야 하는 내용은 표시된 블록 안에 작성하십시오. 그런 다음 CI에서 해당 블록을 확인하십시오. 브랜치와 origin/main에서 sed을 사용하여 블록을 추출하고, diff로 두 내용을 비교한 뒤 차이가 있으면 빌드를 실패 처리하십시오. 대규모 diff 내에서 변경 사항이 눈에 띄지 않고 통과되는 대신, 사람이 직접 변경 사항을 승인하거나 되돌려야 합니다.

AGENTS.md는 얼마나 자주 재생성해야 합니까?

규칙이 잘못된 것을 확인한 풀 리퀘스트 시점에 재생성하십시오. 구조적 변경과 그에 대한 문서는 하나의 diff에 포함되어야 합니다. 그래야만 누군가가 두 가지를 모두 검토할 맥락을 가질 수 있기 때문입니다. 매주 수행하는 정기적인 작업은 브랜치를 벗어난 드리프트를 방지하기 위한 백업 용도이며, main 브랜치에 직접 커밋하기보다는 풀 리퀘스트를 생성하는 방식으로 진행해야 합니다.

빌드 명령은 루트 AGENTS.md에 두어야 합니까, 아니면 하위 문서에 두어야 합니까?

해당 명령을 소유하는 가장 가까운 문서에 두십시오. 저장소 전체 규칙과 하위 인덱스는 루트에 둡니다. 특정 패키지에 적용되는 명령은 해당 패키지의 AGENTS.md에 둡니다. dox는 거리에 따라 충돌을 해결합니다. 더 가까운 문서가 로컬 세부 사항을 제어하며, 하위 문서는 상위 규칙을 약화시킬 수 없습니다. 모든 하위 문서에 동일한 명령을 복사하는 것은 정기적인 작업 시 전체 트리를 다시 작성하게 만드는 원인이 됩니다.

소규모 저장소에서도 dox를 사용할 가치가 있습니까?

대개는 그렇지 않습니다. 테스트 명령 하나와 20줄짜리 AGENTS.md를 가진 단일 패키지는 서서히 노후화되므로, 문제가 발견된 직후 1분 내에 수정할 수 있습니다. dox는 저장소에 서로 다른 규칙을 가진 경계가 여러 개 있거나, 배경 지식이 부족한 기여자가 있을 때 그 가치를 발휘합니다. 이때 문서 체인은 한 사람이 모두 감당할 수 없는 작업을 대신 수행해 줍니다.