Harness Diagnostics

에이전트 협업 환경의 성숙도를 평가하고 실행 가능한 리포트를 생성합니다.

핵심 원칙

Read-only: 기본 동작은 진단/제안만 수행
Evidence-first: 모든 판단은 파일 경로 근거 포함
Principle-driven: 12원칙 + 성숙도 프레임워크 기반 채점
Self-referential: 이 skill 자체도 동일 기준으로 진단 가능

모드 선택

모드	트리거	목적	워크플로우
Setup	새 프로젝트, "환경 구축"	초기 harness 구성 제안	`references/setup-workflow.md`
Audit	"진단", "점검"	점수화 + 개선 로드맵	`references/audit-workflow.md`
Maintenance	"drift", "정리"	변경 감지 + GC 제안	`references/maintenance-workflow.md`

모드가 애매하면 사용자에게 확인한다.

권장 사용 흐름

초기 프로젝트에서 이 skill을 사용할 때는 다음 순서를 권장한다.

프레임워크 공식 스캐폴드로 최소 프로젝트 생성
Setup 모드로 현재 레포 상태 진단
사용자가 별도로 제공한 요구사항을 목표 상태 설계 입력으로 반영
Setup 리포트를 기준으로 AGENTS.md, docs/, lint/test/CI, 구조 규칙을 먼저 정리
그 다음 실제 기능 구현 진행

예:

Next.js: npx create-next-app@latest ... 이후 Setup 실행
Python: uv init 또는 poetry new 이후 Setup 실행
Go: go mod init 이후 Setup 실행

중요:

Setup은 기본적으로 read-only 진단/제안 단계다.
사용자 요구사항은 현재 상태의 근거가 아니라 목표 상태를 위한 설계 입력으로 취급한다.
구현 요청이 함께 들어오더라도, 가능하면 먼저 Setup 리포트로 초기 harness 구조를 고정한 뒤 구현 단계로 넘어간다.

진단 대상

대상	판별 기준	체크리스트
코드베이스	git repo + 소스 존재	`references/codebase-checklist.md`
Skill	`.codex/skills/*/SKILL.md`	`references/skill-checklist.md`
Self	본 skill 자체	`references/skill-checklist.md`

12 Harness Principles

references/principles.md를 기준으로 P1~P12를 0-10점으로 평가한다. P1 Agent Entry Point, P2 Map, P3 Invariant, P4 Convention, P5 Progressive Disclosure, P6 Layered, P7 Garbage Collection, P8 Observability, P9 Knowledge, P10 Reproducibility, P11 Modularity, P12 Self-Documentation.

성숙도 등급

등급	점수	의미
L1	0-19	None
L2	20-39	Basic
L3	40-59	Structured
L4	60-79	Optimized
L5	80-100	Autonomous

가중치/산식은 references/maturity-framework.md를 따른다.

실행 절차

모드 결정
대상 판별 (코드베이스/Skill/Self)
해당 워크플로우 실행
references/report-template.md 형식으로 리포트 출력

자동화 도구

Self 진단 스모크 테스트: scripts/self-audit.sh
Self Meta 동기화: scripts/update-self-meta.sh
점수 계산 스크립트: scripts/calculate-score.js
점수 계산 MD 템플릿: references/score-template.md
점수 계산 JSON 템플릿: references/score-template.json
분기 점검 로그: logs/self-audit-log.md

References

파일	역할
`references/principles.md`	12원칙 판단 기준
`references/maturity-framework.md`	차원/가중치/점수 산식
`references/codebase-checklist.md`	코드베이스 체크리스트 (84항목)
`references/skill-checklist.md`	Skill 체크리스트 (40항목)
`references/setup-workflow.md`	Setup 워크플로우
`references/audit-workflow.md`	Audit 워크플로우
`references/maintenance-workflow.md`	Maintenance 워크플로우
`references/report-template.md`	리포트 출력 형식
`references/score-template.md`	차원/종합 점수 계산 표
`references/score-template.json`	자동 계산 입력 스키마

Examples

파일	내용
`examples/sample-agents-md.md`	AGENTS.md 예시
`examples/sample-setup-report.md`	Setup 리포트 예시
`examples/sample-report.md`	Audit 리포트 예시
`examples/sample-docs-structure.md`	권장 docs 구조

harness-diagnostics