manage-skills

Files (2)

• SKILL.md
• validate-skill-frontmatter.sh · scripts/

SKILL.md (first lines)

> **[워크스페이스 규칙]** 이 스킬이 `CLAUDE.md`를 Edit/Write할 때, `sync-entry-points.js` 훅이 자동으로 `AGENTS.md`와 `GEMINI.md`에 동기화합니다. AGENTS.md/GEMINI.md를 수동으로 업데이트할 필요가 없습니다.

# 세션 기반 스킬 유지보수

## 목적

현재 세션에서 변경된 내용을 분석하여 검증 스킬의 드리프트를 탐지하고 수정합니다:

1. **커버리지 누락** — 어떤 verify 스킬에서도 참조하지 않는 변경된 파일
2. **유효하지 않은 참조** — 삭제되거나 이동된 파일을 참조하는 스킬
3. **누락된 검사** — 기존 검사에서 다루지 않는 새로운 패턴/규칙
4. **오래된 값** — 더 이상 일치하지 않는 설정값 또는 탐지 명령어

## 실행 시점

- **피처 개발 Sync 단계마다** — `issue-driven-development.yaml` 워크플로우에 의해 자동 호출됨 (조건 없이 항상 실행)
- 새로운 패턴이나 규칙을 도입하는 기능을 구현한 후
- 기존 verify 스킬을 수정하고 일관성을 점검하고 싶을 때
- PR 전에 verify 스킬이 변경된 영역을 커버하는지 확인할 때
- 검증 실행 시 예상했던 이슈를 놓쳤을 때
- 주기적으로 스킬을 코드베이스 변화에 맞춰 정렬할 때

## 등록된 검증 스킬

| 스킬 | 설명 | 커버 파일 패턴 |
|------|------|---------------|
| `verify-contract-conformance` | 선언 계약↔구현 심볼 드리프트 | `scripts/conform/**`, `docs/contracts/**` |
| `verify-request-contract` | 원요청 source→증거·권한·리뷰·세션 바인딩·양 클라이언트 동등성 | `.agents/hooks/core/{request-contract*,beh-*,harness-core.js,harness-session-inject.test.js}`, `.agents/context/{request-contract.json,harness.yaml,project-index.yaml,skills-index.yaml,complexity-waivers.json}`, `.agents/requirements/{RCI-*.yaml,_index.yaml,sources/**}`, `.claude/{beh-*,hooks/{request-contract.js,session-inject.js},hooks/beh-*,hooks/e2e/*.sh,hooks/test/**,settings.json,skills/verify-request-contract}`, `.codex/**`, `scripts/{*request-contract*,run-native-harness-tests.cjs}`, `packages/artifacts-spec/**`, `.agents/skills/{manage-skills,review-pass,verify-implementation,verify-request-contract}/**`, `.users/{context/{harness,request-contract}.md,skills/verify-request-contract/**}`, `{AGENTS,CLAUDE,GEMINI}.md`, `package.json`, `.gitignore`, `.gitattributes` |
| `verify-benchmark-contract` | 벤치 스키마·공급자 영수증·HMAC/DPAPI 저널·분석 증거 | `packages/benchmark-contract/**`, `.agents/context/development-model-routing.yaml`, `.users/context/{development-model-routing.md,en/development-model-routing.md}` |
| `verify-product-preservation` | 기존 제품 표면·원요청 권한·기준 버전·검토/배포 상태 | `.agents/workflows/issue-driven-development.yaml`, `.agents/requirements/{_template.yaml,**}`, `.agents/skills/{review-pass,verify-implementation,manage-skills,verify-product-preservation,manage-discord-sessions}/**`, `.agents/context/{harness.yaml,skills-index.yaml}`, `.users/{context/{harness,request-contract}.md,skills-list.md,skills/{verify-product-preservation,manage-discord-sessions}/**}`, `.claude/skills/verify-*`, `{AGENTS,CLAUDE,GEMINI}.md`, `naia-settings/{README.md,messenger-sessions/config.example.json}`, `docs/design/discord-*.md`, project-adapter-declared surfaces/tests/vendor/CI |

## 워크플로우

### Step 1: 세션 변경사항 분석

현재 세션에서 변경된 모든 파일을 수집합니다:

```bash
# 커밋되지 않은 변경사항
git diff HEAD --name-only

# 현재 브랜치의 커밋 (main에서 분기된 경우)
git log --oneline main..HEAD 2>/dev/null

# main에서 분기된 이후의 모든 변경사항
git diff main...HEAD --name-only 2>/dev/null
```

중복을 제거한 목록으로 합칩니다. 선택적 인수로 스킬 이름이나 영역이 지정된 경우 관련 파일만 필터링합니다.

**표시:** 최상위 디렉토리(첫 1-2 경로 세그먼트) 기준으로 파일을 그룹화합니다:

```markdown
## 세션 변경사항 감지

**이 세션에서 N개 파일 변경됨:**

| 디렉토리 | 파일 |
|----------|------|
| src/components | `Button.tsx`, `Modal.tsx` |
| src/server | `router.ts`, `handler.ts` |
| tests | `api.test.ts` |
| (루트) | `package.json`, `.eslintrc.js` |
```

### Step 2: 등록된 스킬과 변경 파일 매핑

위의 **등록된 검증 스킬** 섹션에 나열된 스킬을 참조하여 파일-스킬 매핑을 구축합니다.

경로뿐 아니라 파일의 **역할**을 먼저 분류합니다. 다음 역할은 파일 수와 확장자에 관계없이
검증 대상입니다.

- `requirement_authority`: 원요청, REQ, 승인, tombstone, scope 결정
- `product_surface`: route, root, navigation, entry, public/admin/ops URL, handoff URL
- `regression_oracle`: test, fixture, snapshot, expected-output
- `source_import`: vendor/third-party source, provenance, pristine baseline
- `release_control`: CI/CD, deploy workflow, container, environment gate
- `documentation_contract`: README/AGENTS/design 중 사용자 동작·배포·완료 기준을 정의하는 문서

변경되지 않은 파일도 route/navigation 연결이 끊겨 도달 불가능해졌다면 영향받은 표면으로
포함합니다. `git diff --name-only`만으로 기능 삭제를 판정하지 않습니다.

#### Sub-step 2a: 등록된 스킬 확인

**등록된 검증 스킬** 테이블에서 각 스킬의 이름과 커버 파일 패턴을 읽습니다.

등록된 스킬이 0개인 경우, Step 4 (CREATE vs UPDATE 결정)로 바로 이동합니다. 모든 변경 파일이 "UNCOVERED"로 처리됩니다.

등록된 스킬이 1개 이상인 경우, 각 스킬의 `.agents/skills/verify-<name>/SKILL.md`를 읽고 다음에서 추가 파일 경로 패턴을 추출합니다:

1. **Related Files** 섹션 — 테이블을 파싱하여 파일 경로 및 glob 패턴 추출
2. **Workflow** 섹션 — grep/glob/read 명령어에서 파일 경로 추출

#### Sub-step 2b: 변경된 파일을 스킬에 매칭

Step 1에서 수집한 각 변경 파일에 대해, 등록된 스킬의 패턴과 대조합니다. 파일이 스킬과 매칭되는 조건:

- 해당 스킬의 커버 파일 패턴과 일치
- 해당 스킬이 참조하는 디렉토리 내에 위치
- 해당 스킬의 탐지 명령어에 사용된 regex/문자열 패턴과 일치
- 위 역할 중 하나를 수행하며 변경으로 의미·도달 가능성·release 결과가 달라짐

#### Sub-step 2c: 매핑 표시

```markdown
### 파일 → 스킬 매핑

| 스킬 | 트리거 파일 (변경된 파일) | 액션 |
|------|--------------------------|------|
| verify-api | `router.ts`, `handler.ts` | CHECK |
| verify-ui | `Button.tsx` | CHECK |
| (스킬 없음) | `package.json`, `.eslintrc.js` | UNCOVERED |
```

### Step 3: 영향받은 스킬의 커버리지 갭 분석

영향받은(AFFECTED) 각 스킬(매칭된 변경 파일이 있는 스킬)에 대해, 전체 SKILL.md를 읽고 다음을 점검합니다:

1. **누락된 파일 참조** — 이 스킬의 도메인과 관련된 변경 파일이 Related Files 섹션에 목록되어 있지 않은 경우?

From nextain/naia-adk, Apache-2.0.

More from nextain/naia-adk