gkrtjd99 · gkrtjd99 · May 14, 2026 · May 14, 2026 · May 14, 2026 · May 14, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -32,6 +32,10 @@ jobs:
           bash -n starter-kit/scripts/lint-architecture.sh
           bash -n skill/scripts/scan-project.sh
           bash -n scripts/sync-skill-targets.sh
+          bash -n scripts/check-agents-doc.sh
+
+      - name: Check AGENTS.md Line Limit
+        run: bash scripts/check-agents-doc.sh
 
       - name: Sync Skill Targets
         run: bash scripts/sync-skill-targets.sh

diff --git a/AGENTS.md b/AGENTS.md
@@ -6,21 +6,28 @@ This document is the primary agent entry point for this repository.
 
 1. `ARCHITECTURE.md`
 2. `README.md`
-3. `skill/SKILL.md`
-4. `docs/design-docs/`
-5. `targets/README.md`
-6. `docs/references/`
+3. `docs/references/development-rules.md`
+4. `docs/generated/code-map.md`
+5. `docs/module-contracts/README.md`
+6. `skill/SKILL.md`
+7. `docs/design-docs/`
+8. `targets/README.md`
+9. `docs/references/`
 
 ## Repository Map
 
 - `starter-kit/`: static reference template for generated harness documents
 - `skill/`: canonical `harness-init` skill source
 - `targets/`: generated runtime bundles for supported agent tools
 - `scripts/`: repository automation for syncing runtime bundles
+- `docs/generated/code-map.md`: generated index of reusable repository surfaces
+- `docs/module-contracts/`: module ownership, public surface, and verification contracts
+- `docs/references/development-rules.md`: detailed development and subagent handoff rules
 
 ## Rules
 
 - Agents MUST treat this file as a map, not a full manual.
+- Agents MUST keep this file under 100 lines.
 - Agents MUST keep `skill/` and `targets/` semantically aligned.
 - Agents MUST update `ARCHITECTURE.md` for stable system-map changes.
 - Agents MUST update `docs/design-docs/` for design rationale and tradeoffs.

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -18,17 +18,23 @@ The top-level subsystems are:
 3. `targets/`
    Generated runtime bundles for Claude, Claude Code, Codex, OpenCode, and Antigravity.
 
-4. `.github/workflows/`
+4. `docs/generated/code-map.md` and `docs/module-contracts/`
+   Generated project navigation and module ownership contracts for agents working with small context windows.
+
+5. `.github/workflows/`
    Repository automation that validates documentation, shell scripts, and target-bundle synchronization.
 
-5. `scripts/`
+6. `scripts/`
    Local automation for synchronizing runtime bundles from the canonical skill source.
 
 ## Module Boundaries
 
 - `starter-kit/` owns the copy-and-edit template surface.
 - `skill/` owns the canonical interview flow, generation rules, and shared references.
 - `targets/` owns runtime-specific packaging outputs and install guidance.
+- `docs/generated/code-map.md` owns the generated index of reusable code surfaces across frontend, backend, infra, scripts, shared packages, styles, tests, and generated artifacts.
+- `docs/module-contracts/` owns durable module-level responsibility, public entry point, dependency, and verification contracts.
+- `docs/references/development-rules.md` owns detailed implementation and subagent handoff rules so `AGENTS.md` can stay short.
 - `.github/workflows/` owns repository-level validation and release-gate automation.
 - `scripts/` owns repeatable synchronization of generated runtime bundles.
 
@@ -39,13 +45,16 @@ The top-level subsystems are:
 - `ARCHITECTURE.md` stays focused on stable repository structure.
 - Detailed design rationale and tradeoffs live under `docs/design-docs/`.
 - `skill/SKILL.md` is the canonical source of truth for the `harness-init` workflow.
+- `AGENTS.md` must remain a navigation map rather than a detailed development manual.
+- Generated harnesses must include a code map and module-contract index so subagents can find existing code before adding new files.
 - `targets/` must be generated from `skill/` rather than edited by hand.
 - Repository CI must validate both the root documentation surface and target-bundle synchronization.
 
 ## Where To Read Details
 
 - Design notes: `docs/design-docs/`
 - Skill distribution rationale: `docs/design-docs/skill-distribution.md`
+- Code organization rationale: `docs/design-docs/code-organization-contract.md`
 - Skill rules: `skill/SKILL.md`
 - Template contract: `skill/references/templates.md`
 - Runtime bundles: `targets/README.md`
diff --git a/README.md b/README.md
@@ -76,18 +76,24 @@ Use the harness-init skill to scaffold the project operating documents.
 | `docs/design-docs/index.md` | 설계 결정 목록과 색인 |
 | `docs/design-docs/core-beliefs.md` | 프로젝트의 핵심 원칙과 제약 |
 | `docs/exec-plans/tech-debt-tracker.md` | 기술 부채 추적 |
+| `docs/generated/code-map.md` | 프론트엔드, 백엔드, 인프라, 스크립트, 공유 모듈의 재사용 표면 색인 |
+| `docs/module-contracts/README.md` | 기능과 모듈별 책임, 공개 진입점, 의존성 규칙 색인 |
 | `docs/product-specs/index.md` | 제품 스펙 목록 |
+| `docs/references/development-rules.md` | 상세 개발 규칙과 서브에이전트 handoff 규칙 |
 | `docs/references/*-llms.txt` | 사용 기술 스택의 LLM 참조 문서 |
 | `scripts/init.sh` | 클론 후 빈 폴더 구조를 복원하는 스크립트 |
 
 ### 선택 문서 (프로젝트 성격에 따라 생성)
 
 | 파일 | 생성 조건 |
 | --- | --- |
+| `docs/BACKEND.md` | 백엔드, API, 워커, 큐, 서비스 계층이 있을 때 |
 | `docs/FRONTEND.md` | 프론트엔드 기술 스택이 있을 때 |
+| `docs/INFRASTRUCTURE.md` | 배포, 호스팅, IaC, CI/CD, 런타임 설정이 있을 때 |
 | `docs/SECURITY.md` | 인증/보안이 핵심 제약으로 언급될 때 |
 | `docs/RELIABILITY.md` | 가용성·장애 대응이 중요한 서비스일 때 |
 | `docs/generated/db-schema.md` | 데이터베이스 구조가 있을 때 |
+| `docs/module-contracts/<module>.md` | 다중 파일·장기 유지되는 기능, 패키지, 서비스, 인프라 영역, 스크립트 묶음에 명확한 소유권이 있을 때 (단일 파일·일회성 모듈은 생성하지 않음) |
 | `docs/exec-plans/active/EP-xxxx.md` | 현재 진행 중인 실행 계획이 있을 때 |
 | `docs/product-specs/<feature>.md` | 구체적인 기능 스펙이 있을 때 |
 | `docs/DESIGN.md` | 별도로 정리할 설계 결정이 있을 때 |

diff --git a/docs/design-docs/code-organization-contract.md b/docs/design-docs/code-organization-contract.md
@@ -0,0 +1,37 @@
+# Code Organization Contract
+
+This design note explains why generated harnesses include a code map, module contracts, and cross-cutting file organization rules.
+
+## Context
+
+Agent work often happens through small-context subagents. Those agents can miss existing functions, components, stylesheets, scripts, configuration modules, and infrastructure conventions when the repository does not expose a compact navigation surface.
+
+The same failure mode appears across frontend, backend, infra, scripts, tests, shared packages, generated artifacts, and configuration. A frontend agent may grow one stylesheet into thousands of lines. A backend agent may create a parallel service instead of reusing an existing repository. An infra agent may add a new workflow job instead of extending the existing deployment path.
+
+## Decision
+
+Generated harnesses include `docs/generated/code-map.md` as a concise index of reusable code surfaces. They also include `docs/module-contracts/README.md` as the index for durable module contracts, with optional per-module contracts under `docs/module-contracts/`.
+
+`docs/references/development-rules.md` carries the behavioral rules: search existing code first, reuse owned modules before adding new surfaces, avoid catch-all files, split large files, and update the map when ownership changes. `AGENTS.md` links to that document while remaining a short navigation map. `ARCHITECTURE.md` carries the stable boundaries: public surfaces, dependency direction, file organization, and invariants.
+
+## Rationale
+
+Keeping everything in `AGENTS.md` would make the agent entry point too long and stale. Keeping everything only in generated API docs would miss styles, routes, infrastructure modules, scripts, and conventions that are not represented as exported symbols.
+
+The chosen split keeps instructions short, maps broad, and module contracts specific. This lets a parent agent delegate a narrow task with links to the relevant contract while preserving enough structure for subagents to reuse existing code.
+
+## Authority
+
+When `docs/generated/code-map.md` and `docs/module-contracts/<module>.md` disagree about ownership, public entry points, or dependency rules, the module contract is the source of truth. The code map is a derived index for fast lookup and MUST be updated to match the contract. Agents that find a mismatch MUST fix the code map rather than the contract unless they are explicitly changing the owned module's responsibilities.
+
+## Tradeoffs
+
+The code map can become stale if agents do not update it after changing ownership or entry points. The templates therefore make map updates part of the required workflow.
+
+Per-module contracts add documentation overhead. They are optional until a module has clear ownership, public entry points, or non-obvious reuse rules.
+
+## Consequences
+
+New generated projects have a place to describe frontend, backend, infra, scripts, shared packages, styles, tests, and generated artifacts without creating a separate rule system for each area.
+
+Subagent prompts can reference a small set of files instead of restating the whole repository architecture.
diff --git a/docs/design-docs/index.md b/docs/design-docs/index.md
@@ -4,4 +4,5 @@ This document is the entry point for design notes and rationale.
 
 Read `core-beliefs.md` for guiding principles.
 Read `architecture.md` for implementation rationale and evolution notes.
+Read `code-organization-contract.md` for code-map and module-contract rationale.
 Read `skill-distribution.md` for multi-runtime skill distribution rationale.
diff --git a/docs/generated/code-map.md b/docs/generated/code-map.md
@@ -0,0 +1,28 @@
+# Code Map
+
+This generated index helps agents find and reuse existing repository surfaces before adding new files.
+
+## How To Use
+
+Read the relevant rows before implementation. Update this file when module ownership, public entry points, or file layout changes.
+
+## Surfaces
+
+| Area | Owner Module | Entry Points | Responsibility | Reuse Before Adding | Source |
+| --- | --- | --- | --- | --- | --- |
+| Skill source | `skill/` | `SKILL.md`, `references/templates.md`, `runtime-guides/`, `scripts/scan-project.sh` | Canonical harness-init workflow, templates, runtime install notes, and helper scripts | Existing generation rules, template sections, runtime guide structure | [skill/SKILL.md](../../skill/SKILL.md) |
+| Runtime bundles | `targets/` | Runtime-specific `harness-init/` bundles | Generated installable outputs for supported agent runtimes | `bash scripts/sync-skill-targets.sh`; do not edit bundles by hand | [targets/README.md](../../targets/README.md) |
+| Starter kit | `starter-kit/` | Root docs, optional docs, sample workflows, helper scripts | Static reference shape for generated project harnesses | Existing starter-kit docs before changing templates | [starter-kit/AGENTS.md](../../starter-kit/AGENTS.md) |
+| Repository automation | `scripts/` | `sync-skill-targets.sh` | Synchronize canonical skill source into runtime targets | Existing sync flow and shell conventions | [scripts/sync-skill-targets.sh](../../scripts/sync-skill-targets.sh) |
+| Design docs | `docs/design-docs/` | `architecture.md`, `skill-distribution.md`, `code-organization-contract.md` | Rationale, tradeoffs, and evolution notes | Existing design note before adding new rationale | [docs/design-docs/index.md](../design-docs/index.md) |
+| References | `docs/references/` | `harness-engineering.md` | Durable harness principles and generator contract | Existing reference contract before expanding templates | [docs/references/harness-engineering.md](../references/harness-engineering.md) |
+| Development rules | `docs/references/development-rules.md` | Code discovery, file organization, surface update, handoff rules | Detailed implementation behavior that should not live in `AGENTS.md` | Existing development rules before changing agent behavior | [docs/references/development-rules.md](../references/development-rules.md) |
+| Tests | `tests/` (gitignored, local-only) | Fixtures, prompts, judge rubric, reports | Local skill evaluation inputs and reports | Existing fixtures and rubric before changing eval behavior | `tests/` |
+| Generated docs | `docs/generated/` | `code-map.md`, `db-schema.md` | Generated indexes and derived repository facts | Existing generated document ownership before adding derived docs | [docs/generated/db-schema.md](db-schema.md) |
+| Module contracts | `docs/module-contracts/` | `README.md`, module contract files | Module ownership, public surfaces, dependency rules, verification commands | Relevant module contract before implementation | [docs/module-contracts/README.md](../module-contracts/README.md) |
+
+## Large Files
+
+| File | Lines | Owner | Split Plan |
+| --- | --- | --- | --- |
+| `[path]` | `[count]` | `[owner]` | Add a split plan when a file crosses the repository threshold. |
diff --git a/docs/module-contracts/README.md b/docs/module-contracts/README.md
@@ -0,0 +1,18 @@
+# Module Contracts
+
+Module contracts describe owned repository areas so agents can reuse existing surfaces and avoid catch-all files.
+
+## Contract Index
+
+| Module | Contract | Owner | Scope |
+| --- | --- | --- | --- |
+| Skill source | [skill.md](skill.md) | `skill/` | Canonical skill workflow, templates, runtime guides, helper scripts |
+| Runtime bundles | [targets.md](targets.md) | `targets/` | Generated runtime packages |
+| Starter kit | [starter-kit.md](starter-kit.md) | `starter-kit/` | Static reference harness documents |
+| Automation | [scripts.md](scripts.md) | `scripts/` | Repository synchronization and validation scripts |
+
+## Rules
+
+- Agents MUST read the relevant contract before editing an owned area.
+- Agents MUST add or update a module contract when creating a new long-lived feature, package, service, infrastructure area, or script suite.
+- Contracts MUST name public entry points, reusable internals, forbidden dependencies, local file organization, and verification commands.
diff --git a/docs/module-contracts/scripts.md b/docs/module-contracts/scripts.md
@@ -0,0 +1,29 @@
+# Automation Contract
+
+## Responsibility
+
+`scripts/` owns repeatable repository automation for syncing runtime bundles.
+
+## Public Entry Points
+
+| Name | Kind | Purpose | Source |
+| --- | --- | --- | --- |
+| `sync-skill-targets.sh` | script | Regenerate runtime bundles from canonical skill source | [scripts/sync-skill-targets.sh](../../scripts/sync-skill-targets.sh) |
+
+## Internal Reuse
+
+| Surface | Reuse When | Source |
+| --- | --- | --- |
+| `prepare_bundle` | shell function | Adding or changing runtime bundle sync behavior | [scripts/sync-skill-targets.sh](../../scripts/sync-skill-targets.sh) |
+
+## File Organization
+
+Keep repository-level automation under `scripts/`. Shell constants MUST use uppercase names and local variables MUST use lowercase names.
+
+## Dependency Rules
+
+Scripts SHOULD operate from the repository root and avoid runtime-specific logic outside explicit runtime guide handling.
+
+## Verification
+
+Run `bash -n scripts/sync-skill-targets.sh` after shell changes.
diff --git a/docs/module-contracts/skill.md b/docs/module-contracts/skill.md
@@ -0,0 +1,34 @@
+# Skill Source Contract
+
+## Responsibility
+
+`skill/` owns the canonical `harness-init` workflow, generation rules, template reference, runtime install notes, and helper scripts copied into runtime bundles.
+
+## Public Entry Points
+
+| Name | Kind | Purpose | Source |
+| --- | --- | --- | --- |
+| `harness-init` | skill | Collect project context and generate operating documents | [skill/SKILL.md](../../skill/SKILL.md) |
+| Template reference | document | Define generated document rules and templates | [skill/references/templates.md](../../skill/references/templates.md) |
+| Runtime guides | documents | Provide runtime-specific install and prompt guidance | [skill/runtime-guides/](../../skill/runtime-guides/) |
+| Project scan | script | Inspect a target project document tree | [skill/scripts/scan-project.sh](../../skill/scripts/scan-project.sh) |
+
+## Internal Reuse
+
+| Surface | Reuse When | Source |
+| --- | --- | --- |
+| Optional docs table | Adding generated document types | [skill/references/templates.md](../../skill/references/templates.md) |
+| Generation rules | Changing output behavior | [skill/SKILL.md](../../skill/SKILL.md) |
+| Runtime guide layout | Adding or changing runtime packaging | [skill/runtime-guides/](../../skill/runtime-guides/) |
+
+## File Organization
+
+Keep canonical workflow instructions in `skill/SKILL.md`. Keep reusable template text in `skill/references/`. Keep runtime-specific installation details under `skill/runtime-guides/<runtime>/`. Keep helper scripts under `skill/scripts/`.
+
+## Dependency Rules
+
+`targets/` MUST be generated from `skill/`. Do not copy target-only edits back into `skill/` without checking the canonical contract.
+
+## Verification
+
+Run `bash scripts/sync-skill-targets.sh` after changing `skill/`. Run `bash -n` for changed shell scripts.
diff --git a/docs/module-contracts/starter-kit.md b/docs/module-contracts/starter-kit.md
@@ -0,0 +1,32 @@
+# Starter Kit Contract
+
+## Responsibility
+
+`starter-kit/` owns the static reference shape for generated harness documents.
+
+## Public Entry Points
+
+| Name | Kind | Purpose | Source |
+| --- | --- | --- | --- |
+| Agent entry point | document | Baseline collaboration rules | [starter-kit/AGENTS.md](../../starter-kit/AGENTS.md) |
+| Architecture template | document | Stable project structure map | [starter-kit/ARCHITECTURE.md](../../starter-kit/ARCHITECTURE.md) |
+| Optional docs | documents | Reference examples for generated docs | [starter-kit/docs/](../../starter-kit/docs/) |
+
+## Internal Reuse
+
+| Surface | Reuse When | Source |
+| --- | --- | --- |
+| Generated docs examples | Adding or changing template expectations | [starter-kit/docs/](../../starter-kit/docs/) |
+| Starter-kit scripts | Adding sample validation behavior | [starter-kit/scripts/](../../starter-kit/scripts/) |
+
+## File Organization
+
+Keep sample documents in the same relative paths that generated projects should receive.
+
+## Dependency Rules
+
+Starter-kit changes SHOULD stay semantically aligned with `skill/references/templates.md`.
+
+## Verification
+
+Check the starter-kit tree against the template reference when generated document shape changes.
diff --git a/docs/module-contracts/targets.md b/docs/module-contracts/targets.md
@@ -0,0 +1,34 @@
+# Runtime Bundles Contract
+
+## Responsibility
+
+`targets/` owns generated runtime bundles for supported agent tools.
+
+## Public Entry Points
+
+| Name | Kind | Purpose | Source |
+| --- | --- | --- | --- |
+| Claude bundle | generated bundle | Uploadable Claude skill package | [targets/claude/harness-init/](../../targets/claude/harness-init/) |
+| Claude Code bundle | generated bundle | Filesystem skill package for Claude Code | [targets/claude-code/harness-init/](../../targets/claude-code/harness-init/) |
+| Codex bundle | generated bundle | Filesystem skill package for Codex | [targets/codex/harness-init/](../../targets/codex/harness-init/) |
+| OpenCode bundle | generated bundle | Filesystem skill package for OpenCode | [targets/opencode/harness-init/](../../targets/opencode/harness-init/) |
+| Antigravity bundle | generated bundle | Prompt adapter bundle for Antigravity | [targets/antigravity/harness-init/](../../targets/antigravity/harness-init/) |
+
+## Internal Reuse
+
+| Surface | Reuse When | Source |
+| --- | --- | --- |
+| Sync script | Updating generated bundles | [scripts/sync-skill-targets.sh](../../scripts/sync-skill-targets.sh) |
+| Canonical skill source | Changing bundle content | [skill/](../../skill/) |
+
+## File Organization
+
+Each runtime bundle lives under `targets/<runtime>/harness-init/`.
+
+## Dependency Rules
+
+Agents MUST NOT hand-edit runtime bundle content when the same change belongs in `skill/`.
+
+## Verification
+
+Run `bash scripts/sync-skill-targets.sh` and inspect the resulting target changes.