| name | maintaining-harness |
| description | Use when a project decision changes or the codebase drifts from what a skill or agent documents, and this repository's harness (skills, agents, AGENTS.md, discussions.md) needs to be updated to match. |
Maintaining Harness
.claude/skills, .claude/agents, .codex/agents, AGENTS.md, docs/discussions.md를 최신 상태로 유지하는 절차다. 제품 코드를 검증하는 harness(verification-loop, reviewer, qa)와는 다른 층이므로 섞지 않는다.
언제 쓰는가
- 사용자가 명시적으로 harness 점검이나 특정 skill/agent 수정을 요청할 때만 시작한다.
- 코드 변경마다 자동으로 돌지 않는다. 상시 대조는 판단 오류와 불필요한 토큰 비용만 키운다.
트리거 두 가지
| 트리거 | 신호 | 절차 |
|---|
| 기획/컨벤션 변경 | 사용자가 결정 내용을 명시적으로 알려줌 | 기획 변경 절차 |
| 코드베이스 점검 | 사용자가 harness와 실제 코드의 일치 여부 점검을 요청 | 코드베이스 점검 절차 |
기획 변경 절차
- 결정 내용을 확인 가능한 문장으로 정리한다. 모호하면 사용자에게 확인한다.
AGENTS.md의 Skill Routing과 각 skill 설명으로 영향받는 skill을 찾는다. 여러 skill에 걸치면 전부 나열한다.
docs/discussions.md에 같은 주제의 미결정 항목이 있으면 함께 본다.
- 영향받는 skill 파일을 수정한다. 팀이 확정한 결정이므로 기존 사례를 병기하지 않고 새 기준만 남긴다.
docs/discussions.md에 같은 주제 항목이 있으면 해결됐다고 지우거나 결정 내용으로 갱신한다.
.claude/agents/reviewer.md, .claude/agents/qa.md의 Skill 선택 표나 리뷰 관점이 이 결정과 관련되면 함께 갱신한다.
- 변경한 skill의 예시 코드가 있으면 새 결정과 일치하는지 확인한다.
코드베이스 점검 절차
skill 문서가 서술하는 패턴이 실제 코드와 맞는지 확인한다. 추측하지 않고 코드를 읽어서 검증한다.
- 점검 범위를 정한다. 사용자가 영역을 지정하면 그 범위만, 아니면 전체 skill을 대상으로 한다.
- 각 skill이 서술하는 구체적 패턴(파일 경로, 클래스/함수 이름, 명명 규칙, 호출 순서)을 코드베이스에서 grep과 Read로 확인한다.
- skill 서술과 코드가 다르면 실수(한 곳만 다름)인지 컨벤션 전환(여러 곳이 새 패턴)인지 실제 코드 근거로 판단한다. 근거 없이 추측하지 않는다.
- 판단이 서지 않거나 team 합의가 필요한 항목은 바로 고치지 않고
docs/discussions.md에 현재 코드 기준과 논의 지점을 추가한다.
- skill이 명백히 틀렸거나 낡았을 때(코드가 이미 전부 새 패턴으로 넘어간 경우)만 사용자 확인 후 수정한다.
- harness 밖의 관련 문서(
GA4_EVENTS.md 등)에서도 코드와 다른 사실을 발견하면 코드와 대조해 수정 여부를 사용자에게 확인한다.
일관성 확인
skill이나 agent 파일을 수정한 뒤 아래를 확인한다.
.claude/agents/<name>.md가 원본이므로, .codex/agents/<name>.toml의 developer_instructions가 같은 내용을 요약하고 있는지 확인한다. 서로 모순되면 안 된다.
- 새로 언급한 skill/agent 경로가
AGENTS.md, reviewer.toml, qa.toml에 반영됐는지 확인하고, reviewer.md와 qa.md의 Skill 선택 표에 모두 포함됐는지 확인한다.
.claude/agents/*.md의 frontmatter(name, description, tools)가 유효한지 확인한다.
.codex/agents/*.toml이 파싱되는지 확인한다.
.agents/skills 심볼릭 링크가 깨지지 않았는지 확인한다.
하지 않는 것
- 코드 변경마다 자동으로 도는 훅이나 실시간 대조를 만들지 않는다.
- 한 곳의 예외적 구현만 보고 skill을 바로 고치지 않는다. 여러 사례나 명시적 결정이 근거일 때만 고친다.
- 사용자 확인 없이 팀 컨벤션(discussions.md의 미결정 항목, 코드 동작 스펙)을 단정해 수정하지 않는다.
- 작은 수정에 새 섹션, 새 표, 새 분류 체계를 얹지 않는다. 필요한 줄만 고친다.