| name | findings-audit |
| description | 코드베이스 전반을 감사해 기술 부채·아키텍처 비직관성·품질 게이트 이슈·코드 퀄리티 이슈·버그를 파악하고, 결과를 docs/findings/ 에 FCG 규약대로 문서화한 뒤 commit & push까지 완수한다. 주기 실행을 전제로 기존 findings와 중복되지 않게 증분 감사한다. 트리거 — "부채 파악", "findings 작성", "코드베이스 감사", "감사 돌려줘", "/findings-audit" 및 유사 의도. |
findings-audit
코드베이스 전반 감사 → docs/findings/ 문서화 → commit & push 를 한 번에 수행하는 skill.
주기적으로(스케줄/수동) 반복 실행되는 것을 전제로 하므로, 매 실행은 "전체 재감사"가 아니라
기존 findings 대비 증분 감사다. 사용자 확인 없이 끝까지 완주한다.
0. 대원칙
docs/findings/AGENTS.md 가 단일 규약이다. 실행 시 반드시 먼저 읽고, 파일명·frontmatter·본문 구조·honesty rules를 그대로 따른다. 이 skill과 AGENTS.md가 충돌하면 AGENTS.md가 이긴다.- file:line 증거 없는 주장은 finding이 아니다. 코드를 직접 확인하지 못한 항목은 버린다. ("hunch는 finding이 아니다")
- 중복 생성 금지. 기존 미해결 finding과 같은 이슈를 새 파일로 만들지 않는다 — 기존 파일의
status_notes에 추가하거나 본문을 보강한다.
- 닫힌 이슈를 발견하면 정직하게 닫는다. 기존 finding의 항목이 코드상 이미 해소됐음을 확인하면(grep/Read로 검증),
resolved: true|partial + resolved_by(커밋 SHA) + 증거를 기록한다. 검증 못 했으면 건드리지 않는다.
- 감사 중 코드를 고치지 않는다. 이 skill의 산출물은 문서뿐이다. 수정은 별도 작업/goal로 승격해서 한다.
1. 절차
1-1. 준비
date -u +"%Y-%m-%dT%H%MZ"
docs/findings/AGENTS.md 와 docs/findings/EXAMPLE.md 를 읽는다.- 기존 findings 인벤토리를 만든다: 각 파일의
title / resolved / priority / 핵심 주제를 표로 정리. 이것이 이번 실행의 중복 방지 기준선이다.
- 기준선 이후의 변경 규모를 파악한다: 마지막 findings 배치 커밋 이후의
git log --oneline / git diff --stat. 변경이 집중된 영역을 우선 감사 대상으로 삼는다.
1-2. 5개 차원 병렬 감사
아래 5개 차원을 Explore subagent 병렬 fan-out으로 감사한다 (한 메시지에 5개 Agent 호출).
각 subagent 프롬프트에 반드시 포함할 것: (a) 담당 차원의 정의, (b) 기존 findings 인벤토리 요약(중복 방지), (c) "모든 발견은 file:line + 근거 코드 인용 필수, 추측 금지" 지시, (d) 최근 변경 집중 영역.
| 차원 | 관점 |
|---|
| 기술 부채 | 배포 파이프라인, 의존성(버전 고정·취약·미사용), 문서 드리프트, 죽은 코드, TODO/FIXME 방치 |
| 아키텍처 비직관성 | 새 기여자가 헤맬 구조 — 암묵적 불변식, 우회 패턴, 레이어 침범, 이름과 실제 동작의 불일치 |
| 품질 게이트 이슈 | 커버리지 공백, CI에서 실제로 안 도는 검사, 테스트 실행속도, 유효성(과적합·shallow 성공 선언), flaky |
| 코드 퀄리티 이슈 | 에러 처리 일관성, 무음 catch, 복붙 중복, 타입 우회(any/as), 거대 함수 |
| 버그 | 실제 오동작 — 접근 제어, 데이터 정합성(레이스·캐시 무효화 누락), 경계 조건, 보안 |
1-3. 검증 & 선별
subagent 결과를 모아서:
- file:line 근거가 없는 항목은 직접 Read로 재확인하거나 버린다.
- 기존 finding과 겹치는 항목 → 해당 파일 업데이트 목록으로 분류.
- 신규 항목 → 차원/주제별로 묶어 finding 문서 단위를 정한다 (한 문서는 60초 안에 훑을 수 있게, ~400줄 초과 금지).
- 각 문서에 priority 부여:
P0(데이터 정합성/체인 블로커) / P1(릴리스 전 위험) / P2(릴리스 후 정리).
1-4. 문서 작성
- 신규:
docs/findings/<YYYY-MM-DDTHHMM>-<slug>.md (1-1의 배치 타임스탬프 공유). frontmatter는 AGENTS.md 스키마, 본문은 TL;DR → Body(file:line) → 필요시 Options/Acceptance signal/Migration plan.
- 업데이트: 기존 파일의
status_notes 최상단에 새 줄 추가(newest first), 닫힌 항목은 증거(<file>:<line> 또는 테스트명)와 커밋 SHA를 인용.
- 이번 실행에서 아무것도 발견 못 한 차원이 있으면 문서를 억지로 만들지 않는다.
1-5. commit & push
docs/findings/ 변경 파일만 명시적으로 stage (git add . 금지).- 커밋 메시지:
docs(findings): <요약 — 신규 N건, 업데이트 M건> + 본문에 priority별 불릿 + Co-Authored-By: Claude <noreply@anthropic.com> trailer.
- 첫 push 전
gh auth setup-git (idempotent). push 실패 시 강행(-f) 금지, 보고만.
2. 보고 형식
🔍 findings-audit 완료 (배치 <UTC>)
신규: N건 — <파일명: 한 줄 요약> (priority)
업데이트: M건 — <파일명: 무엇이 닫혔/추가됐는지>
스킵(중복): K건
commit: <hash> (+push 여부)
발견 0건이면 "신규 finding 없음 — 기준선 <마지막 배치> 이후 깨끗" 한 줄로 보고하고 커밋하지 않는다.
