AGENTS.md 감사
프로젝트 상태 및 확립된 정책에 대해 지침을 감사합니다. 에이전트를 오도할 수 있는 주장을 우선시합니다. 문서의 형태나 편집 빈도만으로는 결함으로 판단하지 않습니다. 검사 결과 결함이 발견되지 않으면 결함 없음을 보고합니다. 간단한 부트스트랩 문서와 변경되지 않은 정확한 지침만으로도 충분할 수 있습니다.
기본적으로 인덱스 및 Git 기록을 포함하여 감사를 읽기 전용으로 유지합니다. 수정 사항과 체크포인트 메시지를 검토용으로 준비합니다. 요청이 해당 작업을 승인하는 경우에만 수정 사항을 적용하거나 체크포인트를 생성합니다. 이미 부여된 권한은 다시 묻지 않고 사용합니다. 자동 수정 또는 기타 소스 쓰기 옵션 없이 검사를 실행하고, 사용할 수 없는 실행 전제 조건을 보고합니다.
적용 범위
실제로 검사된 파일, 주장, 기록 및 검사에 대한 적용 범위를 기록합니다.
- 저장소 리비전 및 작업 트리 상태를 기록합니다. 저장소 내 지침 파일, 관련 상위 규칙, 재정의, 가져오기, 링크 및 모듈 맵을 인벤토리합니다. AGENTS.md가 활성 진입점이라고 가정하지 않고 기존 CLAUDE.md 시스템을 포함합니다.
- 의도된 하네스가 어떤 파일을 발견하고 어떤 파일에 명시적 읽기가 필요한지 확인합니다. 사용 가능한 구성 또는 현재 하네스 문서에 대해 관련 로딩 경로 및 크기 예산을 확인합니다. 알려지지 않은 전달은 미검증으로 표시합니다. 파일 이름과 디렉터리 배치만으로는 로딩을 증명할 수 없습니다.
- 확인할 파일 및 주장, 샘플링, 명령어 전제 조건 및 사용 가능한 기록을 명시합니다. 저장소가 더티(dirty) 상태이거나 기록이 얕거나(shallow) 사용할 수 없거나 검사를 실행할 수 없는 경우 판정을 제한합니다. 로컬 변경 사항은 커밋된 스냅샷과 별도로 감사합니다. 해당 SHA에 귀속시키지 마십시오. 로컬 변경 사항이 있는 작업 트리와 같이 커밋된 스냅샷과 다른 파일에서 검사가 실행되는 경우, 실행된 위치와 다른 경로를 명시합니다.
기록 및 이전 발견 사항
Git 저장소의 경우 중간 변경 사항을 검사하기 전에 기저선(baseline)을 선택합니다. Git 기록이 없으면 현재 상태를 확인하고 이력 확인이 불가능함을 보고합니다.
완료된 감사는 저장소 전체에 대해 선언된 검사를 완료한 것입니다. 명시적 한계와 함께 결함, 샘플링 및 사용할 수 없는 검사를 보고할 수 있습니다. 깨끗한 결과는 완료된 검사 내에서 결함이 입증되지 않았음을 의미합니다. 완료할 수 없는 감사는 보고서를 생성하지만 체크포인트는 생성하지 않습니다.
체크포인트는 메시지가 완료된 감사의 보고서와 체크포인트 메시지 템플릿의 트레일러를 저장하는 빈 단일-부모 Git 커밋입니다. 유일한 부모는 감사된 리비전, 즉 해당 감사에서 검사한 커밋된 스냅샷입니다. 로컬 변경 사항은 해당 스냅샷과 별개입니다. 커밋이 기저선 선택의 모든 조건을 충족하는 경우에만 체크포인트입니다. 다른 커밋은 메시지 내용과 관계없이 일반 커밋입니다.
기저선은 대상 브랜치의 첫 번째-부모(first-parent) 기록에서 가장 가까운 체크포인트입니다. 기록 경계를 설정하며, 이는 감사가 감사된 리비전까지의 변경 사항을 검사하는 리비전입니다. 해당 기저선의 새 발견 사항(New) 및 이월 발견 사항(Carried)은 전체 공개 이전 발견 사항의 완전한 집합입니다. 체크포인트를 생성하지 않는 감사는 기저선을 변경하지 않습니다.
부트스트랩 출력은 확인될 때까지 후보 문서로 남아 있으며 자체적으로 기저선을 제공할 수 없습니다.
기저선 선택
HEAD에서 대상 브랜치의 첫 번째-부모 기록을 따라 이동합니다. Agents-Audit-Version 트레일러가 있는 커밋을 후보로 처리합니다. 제목이 아닌 트레일러로 식별합니다. 예:
git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidate> | git interpret-trailers --parse
이 명령어는 후보를 찾습니다. 후보는 메시지와 Git 객체가 다음 모든 조건을 충족하는 경우에만 체크포인트입니다.
- 메시지 템플릿의 모든 트레일러가 충돌하지 않는 하나의 값을 가지며, 버전이 지원되고, 기술 리비전 또는 콘텐츠 해시를 식별할 수 있습니다.
- 커밋에 정확히 하나의 부모가 있습니다. 해당 부모의 전체 SHA는
Agents-Audit-Commit과 같고, 부모 및 커밋 트리는Agents-Audit-Tree와 같습니다. 트리 동등성만으로는 동일한 파일을 생성하는 다른 기록에 대한 재생(replay)을 감지할 수 없습니다. - 커밋이 대상의 첫 번째-부모 기록에 있습니다.
Agents-Audit-Previous는 감사된 리비전의 첫 번째-부모 기록에서 가장 가까운 이전 체크포인트의 이름을 지정하거나, 명시적으로 설정된 초기 기록 경계의 경우none입니다. 명명된 커밋 자체가 체크포인트여야 합니다.- 메시지에는 선언된 커버리지와 함께 템플릿의 모든 보고서 섹션이 포함됩니다.
Agents-Audit-Previous가none이 아닌 이상, 명명된 체크포인트의 새 발견 사항 또는 이월 발견 사항 아래의 각 ID는 이월 발견 사항 또는 종결된 발견 사항 아래에 나타납니다.
각 선행 항목 자체가 체크포인트여야 하므로, 가장 오래된 것부터 후보를 확인하고 각 결과를 재사용합니다. 그러면 모든 커밋이 한 번씩 확인됩니다. 이러한 조건을 충족하는 가장 가까운 후보를 기저선으로 선택합니다. 다른 모든 후보는 기록 창(window)의 일반 커밋으로 처리합니다. 해당 메시지에서 발견 사항이나 종결을 읽지 않고 보고서 및 체크포인트 메시지에서 제외합니다. 선행 항목을 사용할 수 없거나 얕은 기록으로 인해 이러한 검사를 수행할 수 없는 경우, 그 차이를 명시합니다. 알려진 기록 경계를 마지막 몇 개의 커밋으로 조용히 대체하거나 작업을 첫 번째 감사로 선언하지 마십시오. 기저선을 설정할 수 없으면 명시적 한계 내에서 현재 상태를 확인하고 기록 적용 범위를 미검증 상태로 둡니다. 이전 체크포인트가 없는 진정한 첫 번째 감사의 경우 현재 상태를 확인하고 명시적 초기 기록 경계를 명시합니다.
리베이스(rebase), 체리-픽(cherry-pick) 및 스쿼시(squash)는 커밋에 새 부모를 제공하므로 기록 재작성 후 조건을 다시 확인합니다. 기능 기록이 스쿼시된 경우 통합 후 내구성 있는 체크포인트를 설정합니다.
검사
정확성 및 정책
- 프로젝트 구성 및 해당 전제 조건에 대해 명령어를 확인합니다. 적절한 환경에서 실행 가능한 검사를 실행합니다. 실패를 오래된 호출, 구현 결함, 사용할 수 없는 전제 조건 또는 불완전한 검사에 귀속시킵니다. 유효한 테스트 명령어가 회귀를 찾는 것은 오래된 것이 아닙니다.
- 명명된 참조, 경로, 가져오기 및 모듈-맵 항목을 해결합니다. 지침이 누락되었다고 판단하기 전에 이름 변경, 공유 소유권 및 적용 가능한 상위 규칙을 검사합니다. 결함을 입증한 다음, 누락된 기호만으로 판단하지 않고 지침을 따르는 에이전트에게 미칠 가능성이 있는 결과로 심각성을 판단합니다.
- 구현 및 테스트에 대해 중요한 불변 조건(invariants)을 확인하고, 문서 문자열(docstrings) 및 주석을 증거가 아닌 주장으로 처리합니다. 조건의 양쪽에 입력을 사용하여 조건부 주장을 확인합니다. 설명과 정책을 구분합니다. 의도적인 코드도 확립된 경계를 위반할 수 있습니다. 작업의 권한과 기록된 결정을 사용하여 충돌을 해결합니다. 정책을 위반하는 코드와 일치시키기 위해 정책을 다시 작성하지 마십시오.
- 구체적인 실패 또는 회귀 경로에 대해 경고를 검사합니다. 더 이상 사용되지 않거나 피상적인 세부 정보를 제거하고, 이를 우회하는 것이 여전히 현실적인 위험인 경우 유용한 안전장치를 유지하며, 테스트 또는 시행에 의해 이미 적절히 전달된 설명을 다듬습니다. 수정된 실패의 기록보다는 현재의 지침을 선호합니다.
입증된 결함을 오래됨(stale), 모순됨(contradicted), 누락됨(missing), 정책 충돌(policy conflict) 또는 더 이상 사용되지 않는 경고(obsolete warning)로 보고합니다. 불확실한 주장은 미검증 확인 사항으로 유지합니다. 영향을 받은 지침, 저장소 증거, 결과 및 제안된 수정 사항을 포함합니다.
유지보수
기록 경계 이후의 코드, 구성, 종속성 및 지침 변경 사항을 검사합니다. 각 관련 변경 사항을 무효화할 수 있는 주장(변경되지 않은 지침 파일 포함)에 매핑합니다. 커밋 메시지 키워드와 코드 및 지침을 함께 변경한 커밋의 선택적 개수를 사용하여 검사할 변경 사항을 선택하고, 문서 품질을 판단하는 데 사용하지 마십시오.
변경 사항이 문서화된 주장을 무효화하거나 필요한 지침을 누락한 경우에만 유지보수 결함을 보고합니다. 정확한 불변 조건이 여러 번 변경되어도 그대로 유지되도록 허용합니다. 독립적인 수정, 부트스트랩 커밋, 감사 수리 및 체크포인트 커밋을 합법적인 작업으로 처리합니다. 모듈 간 리팩터링이 주장이 여전히 참인 지침을 편집할 필요는 없습니다.
결정 및 경고
버그 발견과 독립적으로 아키텍처 결정을 검사합니다. 미래 변경을 제한해야 하는 결과와 그 이유가 코드에서 명확하지 않은 수용된 선택을 찾습니다. 기록된 설명 또는 결정권자의 확인을 사용합니다. diff(diff)는 변경을 증명하지만 의도는 증명하지 않습니다. 증거가 있고 여전히 유용한 경우에만 재고 조건, 이유 및 조건을 초안으로 작성합니다. 거부된 대안은 언급할 가치가 있을 경우 해당 코드를 변경하는 에이전트가 찾을 수 있도록 영향을 받는 소스의 주석에 남겨 둡니다. 부트스트랩 중에는 현재 소스만 계속 사용하고, Git 기록에서 이유를 채굴하거나 근거를 발명하지 마십시오.
중대하게 진단된 버그의 경우, 교훈이 여전히 비용이 많이 들거나 반복되는 실수를 방지하는지 확인합니다. 유용한 지침을 추가하는 경우에만 증상, 메커니즘 및 인식 또는 회피를 기록하는 간결한 항목을 제안합니다. 추상화를 우회하면 실패가 재도입될 수 있는 경우, 경고를 간결한 안전장치로 바꾸고 이유를 설명합니다. 메커니즘이 사라졌거나, 실수가 피상적이거나, 시행이 이미 교훈을 적절히 전달하는 경우 삭제를 제안합니다. 불확실한 메커니즘은 확인을 위한 제안으로 유지합니다.
형식
정확성 이후에 형식을 확인합니다. 저장소 전체 규칙은 루트 파일에, 모듈이 공유하는 규칙은 소스-루트 또는 패키지 파일(허브)에, 별개의 모듈 규칙은 로컬 파일(리프)에 배치합니다. 별도의 지침이 필요한 범위만 사용합니다. 하나의 파일 프로젝트, 여러 허브 및 생략된 빈 섹션을 허용합니다. 하나의 표준 설명을 유지하고, 검색 기능을 개선할 때 간결한 범위 내 알림과 링크를 허용합니다. 적용 가능한 버전, 확인 날짜, 플랫폼 및 측정 조건을 보존합니다. 더 이상 사용되지 않는 진행 설명, 발명된 근거, 불필요한 중복 및 변경에 더 이상 도움이 되지 않는 지침을 제거합니다. 텍스트가 얼마나 자주 변경되는지가 아니라 유용한 결정으로 구체성을 판단합니다.
보고서
확인된 지침이 정확한지 명시하고 해당 결론을 검사된 주장으로 제한합니다. 리비전, 더티 또는 무시된 콘텐츠 검사, 지침 인벤토리, 확인 또는 샘플링된 주장, 기록 경계, 명령어 결과, 관련 환경 및 버전, 미확인 검사를 기록합니다. 저장소 자체에서 해석 가능하도록 보고서를 유지하고, 증거로 저장소-상대 경로 및 Git 리비전을 사용합니다.
보고서를 최종 확정하기 전에 기저선의 모든 공개 발견 사항을 재확인하고 이월 발견 사항 또는 종결된 발견 사항 아래에 배치합니다.
발견 사항을 다음 섹션으로 구분합니다. 섹션이 비어 있으면 없음을 작성합니다.
- 새롭고 안정적인 ID, 영향을 받는 지침, 증거, 결과 및 필요한 수정 사항과 함께 새 발견 사항을 기록합니다.
- 이월 발견 사항 아래에 기저선의 모든 미해결 발견 사항(해당 기저선이 새로 기록한 발견 사항 포함)을 ID, 소스 체크포인트(처음 기록한 체크포인트), 증거, 결과 및 필요한 수정 사항에 대한 완전한 설명과 함께 이월합니다. 해결을 확인할 수 없는 경우 발견 사항을 공개 상태로 유지하고 확인할 수 없는 증거를 공개합니다.
- 확인된 해결 또는 대체 및 지원 증거와 함께 발견 사항을 종료합니다. 각 종료를 한 번 기록한 후 이후 보고서에서 생략합니다. 각 보고서에서 아카이브를 늘리지 않고 이전 체크포인트에 기록을 유지합니다.
ID를 재사용하지 않고 할당합니다. 예를 들어, 감사별 UTC 타임스탬프와 카운터를 사용하고 이후에 해당 ID를 유지합니다. 보고서에 감사가 완료되었는지 명시합니다. 중단되거나 완료되지 않은 감사는 보고서로 종료됩니다. 입증하는 검사 내에서만 깨끗한 결과를 주장합니다.
체크포인트 메시지
완료된 감사의 전달물의 일부로 다음 메시지를 준비합니다. 외부 이슈 트래커, 로컬 보고서 또는 기타 외부 소스에 대한 포인터가 아닌 감사 보고서 자체를 포함합니다. 표시된 대로 제목이 없는 주제와 트레일러를 정확히 사용하고, 보고서 섹션에는 ## 제목과 빈 줄을 사용합니다. 설치된 경로에 의존하지 않고 완전한 객체 ID와 식별 가능한 기술 리비전 또는 해시를 기록합니다.
chore: 에이전트 문서 감사 기록
## 적용 범위
<저장소-상대 지침 파일 또는 디렉토리>를 검사했습니다.
<수행된 주장 및 검사(샘플링 포함)를 확인했습니다>.
<기록 경계>에서 감사된 리비전까지의 기록을 검사했습니다.
<관련 환경 및 도구 버전, 검사가 실행된 위치>를 사용했습니다.
## 미확인 검사
<완료되지 않은 검사 및 그 이유, 또는 없음.>
## 새 발견 사항
<안정 ID, 영향을 받는 지침 및 섹션, 발견 사항, 증거,
결과 및 각 새 발견 사항에 대한 필요한 수정 사항; 또는 없음.>
## 이월 발견 사항
<안정 ID, 소스 체크포인트 및 각
미해결 발견 사항에 대한 자체 포함 설명(증거, 결과 및 필요한
수정 사항 포함); 또는 없음.>
## 종료된 발견 사항
<안정 ID, 해결 또는 대체, 및 이 감사가 종료하는 각 발견 사항에 대한 지원 증거
; 또는 없음.>
Agents-Audit-Version: 1
Agents-Audit-Commit: <전체 감사된 부모 커밋 SHA>
Agents-Audit-Tree: <감사된 트리 SHA>
Agents-Audit-Skill-Revision: <기술 리비전 또는 콘텐츠 해시>
Agents-Audit-Previous: <기저선 체크포인트 SHA 또는 none>
체크포인트 생성
완료된 감사에 대해서만 그리고 해당 쓰기에 대한 승인이 있는 경우에만 체크포인트를 생성합니다. 감사된 리비전이 여전히 HEAD이고 감사된 지침 및 코드가 해당 트리에 표시되어야 합니다. 먼저 승인된 수정 사항을 커밋하고 체크포인트를 기록하기 전에 결과 스냅샷을 확인합니다. 수정 사항이 감사된 리비전을 변경한 경우 보고서 및 트레일러를 새로 고쳐 확인된 스냅샷을 설명합니다. 커밋되지 않았거나 무시된 콘텐츠는 커밋된 스냅샷에 대한 주장에서 제외하고 결과 적용 범위 제한을 기록합니다. 관찰된 더티 상태에 대해 체크포인트를 기록하는 것을 거부합니다.