코드 조직 계약과 모듈 문서 구조 추가

[gkrtjd99]

변경 목적

서브에이전트가 작은 컨텍스트로 작업할 때 기존 함수, 컴포넌트, 스타일, 스크립트, 인프라 설정을 놓치고 병렬 구현이나 거대한 catch-all 파일을 만드는 문제를 줄이기 위한 문서 계약을 추가합니다.

이번 변경은 AGENTS.md를 상세 개발 매뉴얼로 키우지 않고, 짧은 네비게이션 맵 역할을 유지하면서 상세 규칙을 별도 문서로 분리하는 구조를 적용합니다.

주요 변경

1. 생성 문서 구조 확장

• skill/SKILL.md의 인터뷰 질문을 10개에서 11개로 확장했습니다.
• 새 질문은 명시적인 소유권 또는 module contract가 필요한 주요 코드 영역을 수집합니다.
• 생성되는 기본 문서 세트에 아래 문서를 추가했습니다.
  • docs/references/development-rules.md
  • docs/generated/code-map.md
  • docs/module-contracts/README.md

2. AGENTS.md 역할 재정의

• AGENTS.md는 계속 100줄 이하의 네비게이션 문서로 유지하도록 명시했습니다.
• 상세 개발 규칙은 docs/references/development-rules.md로 이동했습니다.
• root AGENTS.md와 starter-kit/AGENTS.md 모두 읽기 순서, repository map, reference map 중심으로 정리했습니다.

3. 전역 개발 규칙 추가

docs/references/development-rules.md에 다음 규칙을 추가했습니다.

• 새 코드 추가 전 기존 모듈, 컴포넌트, 스크립트, 스타일, 테스트, 생성 파일, 설정을 먼저 검색
• docs/generated/code-map.md와 관련 docs/module-contracts/ 문서를 먼저 확인
• 기존 owned module 재사용 또는 확장 우선
• catch-all 파일 생성/확장 방지
• 400줄 초과 파일은 split 검토
• 800줄 초과 파일은 split 또는 유지 사유 문서화
• public surface, ownership, dependency rule 변경 시 관련 문서 갱신
• 서브에이전트 handoff 시 goal, write scope, read order, done-when, forbidden changes, 재사용/추가/검증 내역 보고

4. Code Map 추가

docs/generated/code-map.md를 추가해 다음 영역의 재사용 표면을 색인화하도록 했습니다.

• frontend
• backend
• infra
• scripts
• shared packages
• styles
• tests
• generated artifacts
• repository-specific docs and targets

이 문서는 서브에이전트가 구현 전에 기존 구조를 빠르게 찾는 지도 역할을 합니다.

5. Module Contracts 추가

docs/module-contracts/README.md와 실제 저장소용 module contract 문서를 추가했습니다.

• docs/module-contracts/skill.md
• docs/module-contracts/targets.md
• docs/module-contracts/starter-kit.md
• docs/module-contracts/scripts.md

각 contract는 책임 범위, public entry points, 내부 재사용 표면, 파일 조직, 의존성 규칙, 검증 명령을 기록합니다.

6. Frontend, Backend, Infrastructure 템플릿 보강

• starter-kit/docs/BACKEND.md 추가
• starter-kit/docs/INFRASTRUCTURE.md 추가
• starter-kit/docs/FRONTEND.md에 styling ownership, reuse rules, file size rules를 보강
• frontend뿐 아니라 backend, infra, scripts까지 같은 조직 규칙을 적용하도록 확장했습니다.

7. 배포용 target bundle 동기화

bash scripts/sync-skill-targets.sh를 실행해 canonical skill/ 변경을 모든 runtime bundle에 반영했습니다.

• Claude
• Claude Code
• Codex
• OpenCode
• Antigravity

8. 평가/설계 문서 갱신

• docs/design-docs/code-organization-contract.md를 추가해 설계 근거를 기록했습니다.
• docs/references/harness-engineering.md의 최소 harness contract를 갱신했습니다.
• skill eval loop 관련 spec/plan 문서의 hard check 기준을 새 구조에 맞췄습니다.

사용자/개발자 영향

• 새 프로젝트를 harness-init으로 생성하면 AGENTS.md가 상세 규칙으로 비대해지지 않습니다.
• 개발 규칙은 docs/references/development-rules.md에서 관리됩니다.
• 서브에이전트는 작업 전에 code-map과 module-contracts를 통해 기존 코드 표면을 확인하게 됩니다.
• frontend CSS, backend service, infra workflow, shell script 등에서 거대한 단일 파일이나 중복 구현이 생기는 문제를 줄입니다.

검증

아래 검증을 실행했습니다.

bash -n scripts/sync-skill-targets.sh
bash -n scripts/check-bundle-structure.sh
bash -n skill/scripts/scan-project.sh
bash -n starter-kit/scripts/check-doc-links.sh
bash -n starter-kit/scripts/lint-architecture.sh
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
git diff --check

커밋

• 41c3002 feat: 코드 조직 계약 문서 추가

[gkrtjd99]

검토했습니다.

확인한 내용:

• 코드맵, 모듈 컨트랙트, 개발 규칙 문서가 AGENTS/ARCHITECTURE/README의 역할 분리와 일관되게 추가되어 있습니다.
• scripts/check-agents-doc.sh와 CI 단계가 AGENTS.md 100줄 제한을 자동 검증하며, 기존 shell/script 스타일과 맞습니다.
• skill/ canonical source와 targets/ runtime bundle이 sync-skill-targets.sh 기준으로 동기화되어 있습니다.
• PR #2 후속 변경까지 반영된 최종 head 기준으로 GitHub Actions Repository CI 2개가 모두 통과했습니다.

로컬 검증:

• bash -n 대상 스크립트 전체 통과
• bash starter-kit/scripts/lint-architecture.sh docs/design-docs 통과
• bash starter-kit/scripts/check-doc-links.sh . 통과
• bash starter-kit/scripts/lint-architecture.sh starter-kit/docs/design-docs 통과
• bash starter-kit/scripts/check-doc-links.sh starter-kit 통과
• bash scripts/check-agents-doc.sh 통과
• bash scripts/sync-skill-targets.sh 실행 후 clean worktree 확인
• bash scripts/check-bundle-structure.sh 통과