후속: 모듈 컨트랙트 트리거 정밀화와 조건부 읽기 가이드

[gkrtjd99]

변경 목적

PR #1(코드 조직 계약과 모듈 문서 구조 추가)의 리뷰 후속 항목 4–7번을 별도 PR로 처리합니다. PR #1 위에 쌓는 stacked PR이며, PR #1이 머지된 후 자동으로 main 대비 diff가 깔끔해집니다.

다루는 리뷰 항목

번호	주제	적용
4	모듈 컨트랙트 생성 트리거 좁히기	skill/SKILL.md와 references/templates.md에 "단일 파일·일회성 모듈은 생성하지 않음" 음(negative) 조건 추가, README.md 표 문구도 같은 의미로 갱신
5	code-map ↔ module-contracts 권위 명시	docs/design-docs/code-organization-contract.md에 Authority 섹션 추가, contract가 source-of-truth, code-map은 derived index임을 규정
6	starter-kit/CLAUDE.md 포인터 보강	Reference Map 섹션 추가, "code map과 module contract를 새 코드 추가 전에 참조" 규칙 추가
7	조건부 로딩 명시	development-rules.md에 Read Order Usage 섹션 추가, 코드 변경 시점에만 code-map/module-contracts 필독, 문서·설정·소규모 버그픽스에는 생략 가능

주요 변경

• skill/SKILL.md: module contract 생성 규칙에 음 조건 추가.
• skill/references/templates.md: Optional Docs 표 module-contracts 행 좁히기, development-rules.md 템플릿에 Read Order Usage 섹션 추가.
• docs/design-docs/code-organization-contract.md: Authority 섹션 추가.
• docs/references/development-rules.md, starter-kit/docs/references/development-rules.md: Read Order Usage 섹션 추가.
• starter-kit/CLAUDE.md: Reference Map 및 사용 규칙 추가.
• README.md: module-contracts 선택 문서 생성 조건 한국어 표현 좁히기.
• targets/*/harness-init/: bash scripts/sync-skill-targets.sh로 5개 runtime bundle 동기화.

검증

bash scripts/sync-skill-targets.sh
bash starter-kit/scripts/check-doc-links.sh .
bash starter-kit/scripts/check-doc-links.sh starter-kit
bash starter-kit/scripts/lint-architecture.sh docs/design-docs
bash starter-kit/scripts/lint-architecture.sh starter-kit/docs/design-docs
bash scripts/check-bundle-structure.sh
bash scripts/check-agents-doc.sh

모두 PASS.

관련 PR

• 베이스: PR 코드 조직 계약과 모듈 문서 구조 추가 #1 (codex/code-organization-contracts). 이 PR의 1·2·3번은 PR #1에 직접 푸시했고, 4–7번은 본 후속 PR에서 다룹니다.

[gkrtjd99]

검토했습니다.

확인한 내용:

• 모듈 컨트랙트 생성 조건을 durable/multi-file surface 중심으로 좁힌 변경이 README.md, skill/SKILL.md, skill/references/templates.md, runtime target bundle에 일관되게 반영되어 있습니다.
• development-rules.md의 Read Order Usage 추가가 AGENTS read order를 실제 작업 맥락에 맞게 해석하도록 보완합니다.
• skill/ 변경 후 bash scripts/sync-skill-targets.sh를 실행해도 worktree가 깨끗하게 유지되어 target bundle 동기화가 맞습니다.

로컬 검증:

• bash -n 대상 스크립트 전체 통과
• root/starter-kit Markdown 링크 검사 통과
• root/starter-kit design-doc lint 통과
• bash scripts/check-agents-doc.sh 통과
• bash scripts/check-bundle-structure.sh 통과