AI Create / Review AGENTS.md
두 가지 모드: 새로운 AGENTS.md 생성 또는 기존 파일을 연구 기반 품질 기준으로 검토
모드 감지
- 사용자가 기존 AGENTS.md를 제공하거나 파일을 가리킴 → 검토 모드
- 사용자가 생성/스캐폴드/작성을 요청함 → 생성 모드
- 모호한 경우 → 질문:
(c) AGENTS.md 새로 만들기 또는 (r) 기존 파일 검토?
생성 모드
1단계: 배치 위치 확인
AGENTS.md를 어디에 배치할까요?
(r) 루트 — 저장소 전체 기준
(p) 경로 — 특정 디렉토리 (경로 입력)
모노레포의 경우: 루트 + 패키지별 파일 제안. 가장 가까운 AGENTS.md가 우선 적용됩니다.
대상 경로에 AGENTS.md가 이미 존재하는 경우 → 질문: 파일이 존재합니다. (r) 기존 파일 검토 / (o) 덮어쓰기 / (Q) 종료?
2단계: 전문가적 사고
작성 전, 이 프로젝트에 대해 다음을 파악하세요:
- 무엇을 알 수 없나요? package.json, 설정 파일, 디렉토리 구조에서 유추할 수 없는 것은?
- 무엇이 위험한가요? 어떤 명령어나 패턴이 조용히 실패를 유발하나요?
- 무엇이 모호한가요? 두 가지 유효한 접근 방식이 있어 에이전트가 잘못 추측할 수 있는 부분은?
- 무엇이 비표준인가요? 프레임워크 기본값과 다른 규칙은?
모든 답변이 "없음"인 경우 — 프로젝트에 AGENTS.md가 필요하지 않을 수 있습니다. 그렇게 말하세요.
package.json이나 빌드 설정이 없는 저장소(문서 전용, 데이터 저장소, 단순 스크립트)의 경우: 미션 + 판단 경계에만 집중 — 툴체인 및 종료 섹션은 적용되지 않습니다.
3단계: 우선순위대로 작성
비가시적 테스트를 통과한 섹션만 다음 순서대로 추가하세요:
- 미션 (2~4문장) — 프로젝트 목적 + 에이전트가 유추할 수 없는 핵심 제약 조건
- 툴체인 레지스트리 — 명령어를 표로, 도구가 강제하는 내용이 아님
- 판단 경계 — 절대 안 함 / 질문 / 항상 해야 함 등급
- 종료 정의 — "완료" = 특정 종료 코드
- 에스컬레이션 규칙 — 막혔을 때 해야 할 일
- 작업별 섹션 — "작성 중... / 검토 중... / 릴리스 중..."
4단계: 검증
- 총 150줄 이하 (최적: 60~100)
- 각 섹션 50줄 이하
- 모든 명령어는 "이 명령어가 완료되었음을 증명하는 것은?"에 답해야 함
- 모든 "하지 마라"는 "대신 이렇게 하라"와 쌍을 이뤄야 함
- 린터 규칙을 반복하지 않음 (툴체인이 우선)
- 명령어 없는 산문 단락 없음
필수 — references/knowledge-base.md 읽기 연구 기반 패턴과 증거 확인.
필수 — references/template.md 읽기 시작 구조 확인.
references/example.md는 사용자가 완성된 AGENTS.md가 어떻게 생겼는지 물어볼 때, 또는 저장소가 JS/TS 모노레포(turborepo + pnpm으로 작업한 예제)인 경우에만 로드 — 그 외에는 건너뛰기.
검토 모드에서는 대상 AGENTS.md가 20줄 미만인 경우 references/knowledge-base.md를 로드하지 마세요 — 본문 체크리스트와 안티패턴 목록만으로 충분히 짧은 파일을 처리할 수 있습니다.
검토 모드
제공된 AGENTS.md를 연구 기반 품질 기준으로 평가합니다.
점수 차원
| 차원 | 가중치 | 확인 사항 |
|---|---|---|
| 신호 밀도 | 25% | 일반/중복 정보 대비 비가시적 전문 지식 라인 비율 |
| 명령 우선 | 20% | 모든 지침에 검증 가능한 명령어 또는 종료 코드 포함 |
| 종료 정의 | 15% | 구체적인 검사가 포함된 명시적 "완료" 기준 |
| 경계 시스템 | 15% | 절대 안 함/질문/항상 해야 함 등급이 명시되고 구체적임 |
| 길이 규율 | 10% | 총 150줄 이하, 섹션당 50줄 이하, 불필요한 내용 없음 |
| 안티패턴 부재 | 15% | 실패가 입증된 패턴이 없음 |
점수 가이드라인
- 성숙한 저장소의 경우 신호 밀도를 엄격하게 채점 — 대부분의 내용이 중복될 가능성이 높음
- 그린필드 프로젝트의 경우 종료/경계에 대해 관대하게 채점 — 아직 CI 게이트가 없을 수 있음
- 모노레포 루트 파일의 경우 길이를 엄격하게 채점 — 모든 세션에서 모든 패키지에 대해 로드됨
- 총점이 40 미만인 경우: 증분 수정보다는 재작성을 권장
안티패턴 체크리스트
다음 중 발견된 사항을 표시하세요 (에이전트 성능 저하가 입증됨):
- 명령어 없는 산문 단락
- 모호한 지시사항 ("주의", "가능한 경우")
- 명시적 순서 없이 상충되는 우선순위
- 이미 린터 설정이 적용하는 스타일 규칙
- 아키텍처 개요 (과도한 탐색 유발)
- 대안 없는 15개 이상의 경고
-
/init명령어로 생성된 LLM 보일러플레이트 - 툴체인이 강제하는 내용을 반복
- 분홍 코끼리 위반 (금지된 개념을 활성화하는 긴 "하지 마라" 목록)
출력 형식
## AGENTS.md 검토: <파일명 또는 경로>
**점수**: X/100
**판정**: [프로덕션 준비 완료 / 개선 필요 / 재작성 권장]
### 강점
- ...
### 문제점 (심각도별)
1. [치명적] ...
2. [높음] ...
3. [낮음] ...
### 재작성 제안
1. ...
2. ...
적용
검토 자체가 결과물이 아닙니다. 더 나은 AGENTS.md가 결과물입니다. 검토 결과를 제시한 후, 다음을 제안하세요:
적용하시겠습니까? (a) 모두 / (s) 번호로 선택 / (n) 적용 안 함
(a) 또는 (s)의 경우: 파일을 제자리에서 편집하여 한 번에 하나의 번호 항목씩 수정한 후, 점수 차원을 다시 실행하고 이전 점수와 함께 새 점수를 보고합니다. 검토가 플래그하지 않은 모든 줄은 그대로 유지됩니다. 검토는 재작성 명령이 아니며, 플래그되지 않은 산문을 조용히 "개선"하면 검토 과정이 작성자의 의도와 어조를 파괴합니다.
사용자가 경로 대신 인라인으로 콘텐츠를 제공했거나 파일을 쓸 수 없는 경우 이 제안을 건너뜁니다. 개선 사항이 적용된 것으로 보고하지 않고 그 이유를 설명하세요.
필수 — references/knowledge-base.md 읽기 각 기준에 대한 연구 증거 확인.
절대 안 함
- 절대 저장소 구조에서 에이전트가 발견할 수 있는 내용을 포함하지 마십시오 — package.json 스크립트, 디렉토리 레이아웃, 설정 파일은 스스로 설명 가능합니다. 이를 반복하면 토큰이 낭비되고 유지 관리 차질이 발생합니다. 대신: 파일을 참조하세요(
see biome.json) 그리고 넘어가세요. - 절대 린터/포맷터 규칙을 다시 말하지 마십시오 — 도구 자체가 제약 조건입니다. 중복은 부실함을 만들고 불필요한 요구 사항은 에이전트 성능을 적극적으로 저하시킵니다. 대신: 실행 명령어만 나열하세요(
Lint: \pnpm lint``). - 절대 "하지 마라"를 "대신 이렇게 하라" 없이 작성하지 마십시오 — 경고만 있는 문서는 과도한 탐색을 유발합니다. 대안 없이 15개 이상의 "하지 마라"가 있으면 에이전트가 보수적이고 덜 생산적이 됩니다. 대신: 모든 금지 사항에 올바른 대안을 쌍으로 제시하세요.
- 절대 150줄을 초과하지 마십시오 — 이 임계값을 넘으면 이익이 역전되고 파일이 적극적으로 품질을 해칩니다. 대신: 세부 사항은 참조 파일로 추출하거나 삭제하세요.
- 절대 LLM 생성 콘텐츠를 최종본으로 사용하지 마십시오 —
/init출력은 에이전트가 이미 알고 있는 내용의 목록일 뿐입니다. 성능을 저하시키고 비용을 증가시킵니다. 대신: 초안 목록으로 취급한 다음 툴체인이 이미 강제하는 모든 내용을 제거하세요. - 절대 산문 단락을 작성하지 마십시오 — 에이전트가 건너뜁니다. 명령어, 표, 검증 가능한 결과가 있는 글머리 기호를 사용하세요. 대신: 명령어 + 종료 코드 + 한 줄 설명으로 변환하세요.