harness-skills · 스킬 설명서

ai-context

CLAUDE.md / AGENTS.md / GEMINI.md 한 개를 대상으로, 업계 기준(Codex · Claude Code · Gemini CLI 스펙) 대비 PASS/WARN/FAIL 판정표와 [OK] 또는 [FAIL] 판정이 붙은 리포트 1건을 산출한다. create / refactor 로 부르면 리포트에 더해 컨텍스트 파일 자체를 쓴다 — 다만 쓰기 전에 항상 사용자 확인을 받는다.

CLAUDE.md / AGENTS.md / GEMINI.md /harness:ai-context 판정표 + Verdict + Next

check — read-only create / refactor — 확인 후 쓰기 기본 action: check baseline 스냅샷 2026-05-11

경계

언제 쓰고, 언제 다른 스킬로 가는가

대상이 세션 시작 시 모델 컨텍스트로 자동 로드되는 파일일 때만 이 스킬이다. 나머지는 전부 형제 스킬의 몫이고, 그중 둘은 SKILL.md 에 명시된 라우팅 정지 조건이다.

이 스킬

컨텍스트 주입 파일 한 개

check(기본) — 기존 파일이 기준에 맞는지 감사
create — 프로젝트 규모에 맞는 템플릿에서 새로 작성
refactor — 비대해진 파일을 중첩 파일로 분할

삭제된 다섯 레거시 스킬(agents-md:{check,create,refactor}, claude-md-check, claude-md-create)의 단일 진입점. 옛 명령은 references/help.md 의 마이그레이션 표에 매핑되어 있다.

다른 스킬로 가는 경우

STOP

SKILL.md → authoring:skill-check
마크다운에 프런트매터까지 있어 헷갈리지만 로딩 모델(트리거 기반)과 검사 항목이 완전히 다르다. 대상이 SKILL.md 면 실행하지 않고 안내 후 멈춘다.

STOP

*.sh → authoring:sh-check
마찬가지로 명시적 라우팅 정지 조건.

넓게

harness-legacy-check
한 파일이 아니라 하네스 전체(컨텍스트 문서 + 스킬 + 워크플로 + settings + 훅 + MCP)를 훑어 .claude/reports/harness-legacy-check.md 로 남기는 read-only 감사.

고침

harness-refactor
그 하네스 리포트의 저위험 항목을 실제로 고친다. 이름이 닮은 ai-context refactor 는 컨텍스트 파일 한 개만 분할한다 — 대상이 다르다.

인터페이스

호출 형식과 인자

/harness:ai-context [action] [path]
/harness:ai-context [action] [--file PATH] [--type TYPE]
/harness:ai-context -h | --help | help

references/help.md 가 1차 근거다. 위치 인자는 [action] [path] 순이며, 알 수 없는 action 이 오면 help 를 출력하고 멈춘다.

인자 / 플래그 — 근거: references/help.md
인자 / 플래그	기본값	설명
`action`	`check`	`check` / `create` / `refactor` / `help` 중 하나
`path`	자동 탐지	대상 파일 경로를 직접 지정
`--file PATH`	—	위치 인자 `path` 와 같되 우선한다
`--type TYPE`	파일명에서 유추	어댑터 강제: `agents` / `claude` / `gemini`
`-h` / `--help` / `help`	—	`references/help.md` 를 그대로 출력하고 중단

자동 탐지와 타입 매핑

cwd 기준 우선순위는 CLAUDE.md → AGENTS.md → GEMINI.md. 파일명 → 타입은 CLAUDE.md→claude, AGENTS.md→agents, GEMINI.md→gemini 이고, 비표준 파일명은 --type 으로 덮어쓴다.

예시

/harness:ai-context — 자동 탐지 후 check. 파일이 하나뿐일 때만 권장
/harness:ai-context check AGENTS.md — CLAUDE.md 도 있을 때 대상 명시
/harness:ai-context check --file ./docs/AGENTS.md — 루트 밖 경로 감사
/harness:ai-context create --type agents — 새 AGENTS.md 작성 흐름
/harness:ai-context refactor — 분할 계획 제시 후 확인받아 실행

동작

네 단계, 그리고 액션별 분기

인자 파싱

$1 이 -h / --help / help 면 references/help.md 를 그대로 출력하고 즉시 멈춘다. 이때는 다른 파일을 전혀 읽지 않는다.
대상 파일 결정

--file(또는 위치 인자)이 있으면 그것을, 없으면 우선순위대로 자동 탐지. 파일이 여러 개면 check 는 최상위 하나만 감사하고 나머지는 WARN, create / refactor 는 후보를 출력하고 사용자에게 묻는다 — 자동으로 고르지 않는다. 하나도 없으면 check / refactor 는 harness:ai-context create 힌트와 함께 중단.
액션별 분기 — 탭을 눌러 확인

read-only. references/checks.md 의 코어 검사 C1~C7 에 더해 타입별 어댑터 검사를 돌리고, 각 판정에 근거가 된 라인을 인용한다. 파일은 절대 건드리지 않는다.

코어 C1~C7
Role/Purpose · Operational Commands · Loading & Scope Model · Modular References · Naming Conventions · Constraints · Size

agents
A-AG1~4 — Discovery · Override/fallback · Payload budget · Context Map

claude
A-CL1~4 — Reference-by-path · Permission Control · Thin Orchestrator · Local+rules layout

gemini
A-GE1~3 — Hierarchy · /memory·imports · .geminiignore
리포트

액션이 무엇이든 references/report-template.md 형식으로 출력한다 — 헤더(File / Kind / Baseline 스냅샷 날짜), 검사 결과 표, Verdict, WARN·FAIL 만 담는 Issues & Improvements, 마지막의 Next: 줄.

전부 PASS
[OK]

WARN 만
[OK] — 경고 개수를 표면에 노출

FAIL 하나라도
[FAIL]

N/A 는 집계에서 제외한다.

제약

주의사항과 안전 계약

절대 하지 않는 것

check 는 감사 전용 — 어떤 경우에도 대상 파일을 수정하지 않는다.
create / refactor 는 덮어쓰기 전 항상 확인 — 계획을 먼저 제시하고, 동의 전에는 쓰지 않는다.
컨텍스트 파일이 여러 개일 때 자동 덮어쓰기는 절대 허용되지 않는다. CLAUDE.md 와 AGENTS.md 가 공존하는 흔한 상황에서, 어느 쪽을 손댈지는 기계가 아니라 사람이 정한다.
SKILL.md / *.sh 에는 실행하지 않고 라우팅 후 멈춘다.
--file / --type 오버라이드는 자동 탐지보다 항상 우선한다.

멈추는 조건

대상 파일이 없는데 action 이 check/refactor · 파일이 여러 개인데 action 이 create/refactor · 대상을 읽을 수 없음(원인 에러와 함께 중단) · 위의 두 라우팅 조건. Step 1~3 이 라우팅 정지나 help 출력이 아닌 진짜 이유로 실패하면 리포트 템플릿에 Verdict=[FAIL] 로 기록하고 멈춘다 — 조용히 넘어가지 않는다.

근거의 출처

어댑터 검사의 판정 근거는 지어내지 않고 references/industry-baseline.md 를 인용한다. Codex · Claude Code · Gemini CLI 공식 문서의 스냅샷이며 스냅샷 날짜(현재 2026-05-11)를 함께 들고 있다. 리포트 헤더의 Baseline: 이 그 날짜를 그대로 노출하므로 어떤 시점의 스펙으로 판정됐는지 되짚을 수 있다.

자동 탐지의 함정

우선순위가 CLAUDE.md 부터라서, AGENTS.md 를 감사하려는 저장소에 CLAUDE.md 가 함께 있으면 인자 없는 호출은 CLAUDE.md 를 잡는다. AGENTS.md 가 CLAUDE.md 를 가리키는 심볼릭 링크인 흔한 배치에서는 결과가 같아 보이지만, 그때도 리포트의 Kind: 는 달라진다(agents 어댑터 vs claude 어댑터). 어느 파일을 어느 어댑터로 볼지 확정하려면 경로를 명시하라.