Imported from thsvkd/naver-post-crawler (AGENTS.md). Install upstream with npx skills add thsvkd/naver-post-crawler. Copyright stays with the author.

AGENTS.md

상세한 가이드라인 및 스펙은 docs/SPEC.md를 참조.

명령어

정의

용어 정의

• 테스트 케이스 리스트: R1에서 인간과 합의한 케이스 리스트. 테스트 코드가 아님.
• 테스트 코드: R2에서 테스트 케이스 리스트를 1:1로 번역한 코드.
• 핸드오프 문서: 테스트 케이스 리스트 + 핵심 결정 + 기각한 대안 + 관련 코드 포인터를 포함한 문서. R2에서 테스트 코드 작성 시 참조.

완료(GREEN)의 정의

테스트는 기능의 SSoT다. 따라서 green = 완료가 성립하도록 테스트를 작성(불신 전제의 수동 재검증이 아니라, 신뢰 가능하게 만드는 것이 목표).

• 구체적으로 green은 다음을 뜻한다:
  • R1에서 인간과 합의해 확정한 테스트 케이스 리스트가 정의.
  • 확정 테스트 케이스 리스트를 올바르게 코드로 인코딩.
  • 각 테스트 코드가 동작을 진짜로 단언함(뮤테이션으로 검증).
  • 모두 통과.
• 테스트 케이스 리스트 외의 케이스는 완료 범위 밖이며, 유지보수 루프로 회귀 테스트와 함께 테스트 케이스 리스트에 추가한다(그 순간부터 완료의 일부가 된다).

적대적 리뷰 루프 정의

• 구현한 내용에 대해서 리뷰하는 루프. 다음과 같은 과정을 거친다.
  1. 구현자가 코드를 작성.
  2. 적대적 리뷰어를 호출하여 리뷰를 진행.
  3. MEDIUM 이상의 피드백이 있으면 구현자에게 피드백을 전달.
  4. 구현자는 피드백을 반영하여 다시 코드를 수정.
  5. 리뷰어는 수정된 코드에 대해 다시 리뷰를 진행.
  6. 리뷰어가 더 이상 MEDIUM 이상 지적이 없다고 판단할 때까지 반복.
  7. 루프 종료 후 LOW 피드백을 출력하고, 반영 여부는 인간 검수 게이트에서 결정.
• 리뷰어는 반드시 **신선한 컨텍스트(별도 서브에이전트)**에서 실행한다. 구현 대화 내 자기검토 금지.
• 피드백 레벨:
  • CRITICAL: 동작 오류, 보안 취약점, 데이터 손실 위험. 즉시 반영.
  • HIGH: 테스트 케이스 미커버, 잘못된 단언, 엣지케이스 누락, 명확한 설계 결함. 루프 내 반영.
  • MEDIUM: 나쁜 관행, 미래 버그 가능성, 유지보수성 저해. 루프 내 반영.
  • LOW: 스타일·이름·취향 수준. 루프 종료 후 인간 결정.

워크플로우

R0. 작업 유형 판별

먼저 유형을 결정한 후, 동작을 분기한다.

• 기능(feature): 아래의 전체 R1->R4 워크플로우를 실행.
• 버그(bug): 먼저 버그를 재현하는 RED 회귀 테스트 코드를 작성하고(이미 담당 테스트 코드가 있다면 RED가 되게 수정) GREEN이 되도록 구현한다.
• 리팩토링(refactor): 동작 불변이 완료 기준. 새 RED을 작성하지 않는다. 기존 테스트 코드가 계속 green임을 보장하고, 커버리지가 부족하면 characterization 테스트 코드를 먼저 보강한 뒤 변경한다.

R1 - 계획 + 합의 (코드 작성 금지)

우선순위: 근본 원인 해결 > 최소 변경. 근본 해결의 범위 안에서 최소·정당한 변경.

1. PRD
   • 기존 코드·패턴을 조사하면서 기획 의도·해결하려는 문제를 명시한다.
2. 테스트 케이스 합의(grilling)
   • 사용자와 결정 트리의 가지를 끝까지 내려가며, "이 테스트 케이스 집합 통과 = 완료"라는 인수 기준을 번호 매긴 리스트를 구현 전에 확정한다(Test-N).
   • 모호한 어휘는 docs/CONTEXT.md에 고정한다.
3. 인간 검수 게이트
   • 인간 사용자가 이 테스트 케이스 리스트가 완료의 정의로 충분한지, 또는 빠진 게 있는지를 검수한다. — 이 게이트는 인간만 닫을 수 있다(AI 리뷰로 대체 불가).
   • 테스트 케이스가 많은 경우(10개 이상) 상호작용 가능한 html문서를 작성하여 검수를 용이하게 한다.
4. 핸드오프 문서 작성
   • 메인 에이전트가 탐색 부산물은 버리고 합의를 고충실도로 외부 문서화한다.
   • 포함하는 것.
     • 테스트 케이스 리스트.
     • 핵심 결정.
     • 기각한 대안.
     • 관련 코드 포인터 .
   • 이 문서가 이후 새 컨텍스트를 가진 에이전트들의 입력이 된다.

R2 - TDD (새 에이전트로 위임)

핸드오프 문서가 충실하면, 새 컨텍스트 에이전트로의 위임이 컨텍스트 오염과 번역 손실을 동시에 낮춘다. 분리의 핵심 경계: 테스트 작성자 ≠ 구현자가 되도록 한다. 구현자가 테스트에 맞춰 코드를 특수처리하는 자기참조를 차단한다.

1. 테스트 코드 작성
   • 새로운 컨텍스트를 가지는 에이전트가 핸드오프의 테스트 케이스 리스트를 1:1 매핑하는 테스트 코드를 작성한다.
   • 새 케이스를 추가·재해석하지 않는다.
   • 각 테스트에 covers: Test-N 태그를 단다.
2. 테스트 코드에 대한 적대적 리뷰 루프 실행
   • 작성한 테스트 코드가 핸드오프 문서를 충실히 따르는지 리뷰한다.
3. RED 확인
   • 각 테스트가 의도한 단언 실패로 RED임을 실행 출력으로 확인한다.
4. 실제 구현 진행
   • 핸드오프 문서를 참고하여 구현을 진행한다.
   • 테스트를 약화·skip·삭제해 green에 도달 시도 금지.
5. GREEN 확인
   • 테스트 실제 실행 출력으로 확인한다.
   • 자기보고("통과한 것 같다") 금지.
   • 간단한 뮤테이션 테스트를 실행해 단언이 충분히 강력한지 확인한다.
   • 단언이 약하면 테스트 코드를 보강한다.

R3 - 검증 루프

1. 구현 코드에 대한 적대적 리뷰 루프 실행
   • 작성한 구현 코드가 핸드오프 문서를 충실히 따르는지 리뷰한다.
2. AI slop 제거
   • /ai-slop-cleaner로 검토한다.
3. E2E 실측 검증
   • 자동화 테스트로 검증하기 어려운 영역(시스템 통합, 실제 환경 의존 동작)에 한정해 실제 실행으로 검증한다.
   • 테스트 코드가 이미 검증한 동작은 수동으로 재확인하지 않는다. 실패 시 R2 4번 단계(실제 구현 진행)로 되돌아간다.
4. 완료 증거 게이트: 추정으로 완료를 주장하지 않는다. 증거 번들을 산출한다:
   • 실행한 정확한 명령어와 출력(테스트/린트/타입체크/빌드 등).
   • 변경 diff와 영향 범위, 테스트 케이스 리스트 <-> 테스트 코드 대응표.
   • 구현 중 내린 가정·결정, R1 합의 대비 이탈 사항.

R4 - 마무리

1. 필요 시 문서를 업데이트한다.
2. 인간 검수용 HTML 보고서를 작성한다.
   • 인간용: 문제/원인/해결/결과가 잘 드러나게 작성된 인터랙티브 보고서.
   • 검증 증거: R3의 증거 번들 포함.
   • 테마: 라이트 모드.
3. 인간 승인 게이트
   • 사용자가 보고서를 검수하고 승인한다(합의 <-> 구현물 대조).
4. 커밋
   • 승인된 경우에만 진행.
   • 올바른 디렉토리 확인.
   • 커밋은 논리적 변경 단위로.
   • 테스트 + 구현을 함께 커밋.
   • 관련 변경점만 커밋.
   • 승인 전 push 절대 금지.

규칙

• 하드코딩 금지.
  • 대신 설정/환경변수 사용.
• 문제를 우회/회피 금지.
  • 증상만 덮지 말고 재현 -> 원인 가설 -> 가설 검증 테스트 -> 수정 순으로 근본 해결한다.
• 기존 패턴/네이밍을 무시한 새 패턴 도입 금지.
  • 도입 전 동일 계층의 기존 구현을 1개 이상 읽고 그 시그니처/네이밍을 따른다.
• 사용자 질의 시 각 항목에 번호를 붙여 명확히 소통한다.

강제 항목

• RED/GREEN 실행 증거 -> Stop agent-hook(테스트 스위트 실행·결과 확인 후에만 종료 허용).
• 신선 컨텍스트 리뷰어 -> 공식 code-review 플러그인 / 다른 모델 워커.
• 자동 포맷 -> PostToolUse 훅(매 Write/Edit).
• 시크릿 절대 커밋·하드코딩 금지 -> .env/시크릿 매니저 + gitleaks pre-commit + .env 경로 PreToolUse 차단.
• 승인 없이 git push 금지 -> 권한 설정 + pre-push 훅.
• 무승인 허용: 읽기, 단일 파일 린트/타입체크, 특정 테스트.
• 승인 필요: 패키지 설치, push, 전체 빌드/E2E, 파일 삭제, 인프라 변경.

Git 컨벤션

• 커밋 메시지는 항상 영어. Conventional Commits 준수.
• 제목: <type>(<scope>): <subject>. 본문(필요 시): - [내용].
• 사용자 이름·이메일은 git config user.name / git config user.email 출력 사용.
• Co-Authored-By: / Made-with: 금지. 트레일러는 아래 형식만:

  Signed-off-by: {사용자 이름} <{사용자 이메일}>
  Assisted-by: Claude Code (<model-id>)