에이전트 준비 상태 감사
현재 레포지토리를 아래 체크리스트에 따라 감사하고, 격차를 보고합니다. 읽기 전용 감사: 레포지토리 파일을 절대 수정, 생성, 삭제하지 않습니다.
1단계: 스택 파악
판단하기 전에 다음을 식별합니다:
- 언어, 프레임워크, 패키지 매니저, 모노레포 구조
- 사용 중인 린터, 포맷터, 타입체커
- 테스트 러너
- 훅 매니저 (husky, lefthook, pre-commit, simple-git-hooks, 일반 .git/hooks)
- CI 시스템 및 설정 파일
- 에이전트 지시 파일 (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions 등)
- 스킬, 런북, 프롬프트, 워크플로 문서가 포함된 디렉터리
이 레포지토리가 실제로 사용하는 도구를 기준으로 평가합니다. 현재 도구로 작업을 수행할 수 없는 경우가 아니라면 도구 교체를 권장하지 마십시오.
예산
- 디렉터리 목록, 설정 파일, 지시 파일부터 시작합니다. 전체 소스 파일을 읽는 대신 grep, 개수 세기, 파일 목록을 사용합니다.
- 주요 패키지당 최대 3개의 대표 파일만 샘플링합니다.
- 레포지토리가 너무 커서 모두 다룰 수 없는 경우, 검토하지 않은 부분을 명시합니다.
2단계: 각 체크리스트 항목 평가
각 항목에 대해 하나의 상태를 할당합니다:
- PASS: 명확히 갖추어져 있고 작동 중
- PARTIAL: 존재하지만 불완전, 구식, 강제되지 않음, 또는 일관성 없음
- MISSING: 확인 결과 존재하지 않음
- N/A: 이 스택에 해당하지 않음 (이유 설명)
- UNCLEAR: 확인할 수 없음 (방해 요인, 예: 외부 CI 또는 검토하지 않은 레포지토리 부분 명시)
모든 상태는 증거(파일 경로, 설정 키, 15단어 미만의 짧은 인용 스니펫)로 뒷받침합니다. 추측하지 마십시오: 확인했지만 찾지 못하면 MISSING으로 표시하고, 확인할 수 없으면 UNCLEAR로 표시합니다.
체크리스트
- 공유 에이전트 지시
- 모든 에이전트와 새 개발자가 읽는 단일 루트 레벨 지시 파일
- 코드 스타일 규칙 (내보내기 스타일, 임포트 구조, 파일 구성, 안티패턴) 포함
- 신뢰 경계에서 외부 데이터의 유효성을 검증하도록 요구
- 어떤 테스트를 작성할 가치가 있는지 명시
- 완료 게이트 정의: 커밋 전에 린트, 타입체크, 관련 테스트 통과 필수
- 최신 상태이고 구체적임. 실제 코드에서 3~5개 규칙을 무작위로 확인하여 코드가 규칙을 따르는지 보고
- 레포지토리 내 워크플로 스킬
- 반복 워크플로가 코드 옆에 단계별 스킬 또는 런북으로 문서화됨
- 범위: 커밋, PR 열기/스태킹, 코드 리뷰, CI 통과, 의존성 변경, 로컬라이제이션
- 스택별 워크플로 포함 (데이터 레이어, 라우터, 디자인 시스템, 코드 생성 등)
- 각 스킬에 트리거, 순서 단계, 완료 정의가 있음
- 스킬이 단일 진실 공급원이며, 중복되거나 모순되지 않음
- 린트 규칙으로 강제되는 컨벤션
- 문서화된 컨벤션에 일치하는 린트 규칙이 있음
- 커스텀 린트 규칙 또는 플러그인이 프로젝트별 사용 (데이터 페칭, 스타일링, 테스트, 번역)을 다룸
- 일반적인 에이전트 실수에 대한 안티패턴 규칙 존재: 체인 또는 불필요한 타입 단언, 느슨한 타입 파라미터(unknown/any), 빈 객체의 조건부 스프레드, 추가로 이 코드베이스에서 발견된 반복적인 저품질 패턴
- 규칙은 경고가 아닌 오류이며, 포괄적인 비활성화 없음
- 자동화된 게이트
- 사전 커밋 훅이 변경된 코드를 포매팅, 린트, 타입체크
- 사전 푸시 훅이 영향을 받는 패키지(종속 항목 포함)를 린트 또는 테스트
- CI가 동일한 검사를 다시 실행하여 훅을 우회할 수 없음
- 훅이 합리적으로 빠름
- 훅이 연결됨: 훅 설정이 커밋되어 있고, 설치 단계(prepare 스크립트, 설정 문서, core.hooksPath)가 존재하며, 호출하는 명령어가 존재함. 파일을 읽어 확인하십시오. 훅을 절대 실행하지 마십시오.
- 감독 및 구조
- 아키텍처 결정이 문서화됨
- 병합 전에 PR 리뷰 필수 (브랜치 보호 또는 CODEOWNERS 확인 가능한 경우)
- 패키지 및 모듈 경계가 명확하고 강제됨
3단계: 문서화되지 않은 컨벤션 찾기
코드에서 일관되게 적용되지만 어디에도 기록되지 않은 패턴, 그리고 에이전트가 자주 실수하는 패턴 (느슨한 타이핑, 검증되지 않은 외부 데이터, 일관성 없는 내보내기, 중복 로직)을 샘플링합니다. 지시 파일에 추가하거나 린트 규칙으로 전환할 상위 5개 후보를 나열합니다.
4단계: 보고
다음을 생성합니다:
- 요약 표: 항목, 상태, 한 줄 증거
- "격차" 섹션: 각 PARTIAL, MISSING, 또는 UNCLEAR 항목, 무엇이 잘못되었는지, 에이전트 신뢰성에 왜 중요한지
- 우선순위가 지정된 권장 목록 (높은 레버리지 순), 각각 구체적인 다음 단계와 대략적인 노력(소/중/대) 포함, 이 레포지토리의 기존 도구 관점에서 표현
- 3단계의 상위 5개 후보 컨벤션
직접적으로 서술하십시오. 칭찬으로 내용을 늘리지 마십시오. 어떤 것이 괜찮으면 PASS라고 말하고 넘어가십시오.
보고서 작성 후, 누락된 부분(초기 지시 파일, 스킬 템플릿, 린트 규칙 스텁)을 구성하는 것을 제안하지만, 요청받기 전까지는 아무것도 생성하지 마십시오.