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

README.md

@@ -93,7 +93,7 @@ Use the harness-init skill to scaffold the project operating documents.
 | `docs/SECURITY.md` | 인증/보안이 핵심 제약으로 언급될 때 |
 | `docs/RELIABILITY.md` | 가용성·장애 대응이 중요한 서비스일 때 |
 | `docs/generated/db-schema.md` | 데이터베이스 구조가 있을 때 |
-| `docs/module-contracts/<module>.md` | 기능, 패키지, 서비스, 인프라 영역, 스크립트 묶음에 명확한 소유권이 있을 때 |
+| `docs/module-contracts/<module>.md` | 다중 파일·장기 유지되는 기능, 패키지, 서비스, 인프라 영역, 스크립트 묶음에 명확한 소유권이 있을 때 (단일 파일·일회성 모듈은 생성하지 않음) |
 | `docs/exec-plans/active/EP-xxxx.md` | 현재 진행 중인 실행 계획이 있을 때 |
 | `docs/product-specs/<feature>.md` | 구체적인 기능 스펙이 있을 때 |
 | `docs/DESIGN.md` | 별도로 정리할 설계 결정이 있을 때 |

docs/design-docs/code-organization-contract.md

@@ -20,6 +20,10 @@ Keeping everything in `AGENTS.md` would make the agent entry point too long and
 
 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.

docs/references/development-rules.md

@@ -3,6 +3,13 @@
 This document holds detailed development rules that should not live in `AGENTS.md`.
 `AGENTS.md` stays a short navigation map.
 
+## Read Order Usage
+
+- The `AGENTS.md` Read Order is a list of documents to consult when relevant, not a checklist to read in full for every task.
+- Agents MUST always read `ARCHITECTURE.md` for structural context.
+- Agents MUST read this file (`development-rules.md`), `docs/generated/code-map.md`, and the relevant `docs/module-contracts/` files only when adding, refactoring, or removing code or modules.
+- Agents MAY skip the code map and module contracts for documentation-only tasks, configuration tweaks, or scoped bug fixes that do not change module boundaries or public surfaces.
+
 ## Code Discovery
 
 - Agents MUST search existing modules, components, scripts, styles, tests, generated files, and configuration before adding new code.

skill/SKILL.md

@@ -48,7 +48,7 @@ Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder
 - Generate detailed design notes under `docs/design-docs/` only when they are justified by the project.
 - When generating `docs/PLANS.md`, follow the structure encouraged by the OpenAI Codex exec-plans article.
 - Generate optional documents according to the condition table in `references/templates.md` — each optional document has an explicit condition; generate it only when that condition is met.
-- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules.
+- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules. Do NOT generate a contract for small, single-file, or short-lived modules; treat the contract as documentation overhead that pays off only for durable, multi-file surfaces.
 - Populate `docs/generated/code-map.md` with concise entries for important features, modules, scripts, infra entry points, shared utilities, styling surfaces, tests, and generated artifacts.
 - If `referenceTools` is present, generate one `docs/references/<tool>-llms.txt` per tool.
 - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`.

skill/references/templates.md

@@ -32,7 +32,7 @@ Generate each document only when its stated condition is met:
 | `docs/SECURITY.md` | Authentication, authorization, or RLS is a core constraint |
 | `docs/RELIABILITY.md` | Availability, resource limits, or fault tolerance matter (free-tier infra, SLAs, uptime targets) |
 | `docs/generated/db-schema.md` | A database schema is described or implied |
-| `docs/module-contracts/<module>.md` | A module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules |
+| `docs/module-contracts/<module>.md` | A durable, multi-file module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules; skip for small, single-file, or short-lived modules |
 | `docs/exec-plans/active/EP-xxxx.md` | At least one in-progress task maps to an execution plan |
 | `docs/exec-plans/completed/EP-xxxx.md` | A previously completed execution plan exists |
 | `docs/product-specs/<feature>.md` | A concrete feature with scope, constraints, and done-when criteria is described |
@@ -342,6 +342,13 @@ Include concise commands, constraints, and known pitfalls.
 This document holds detailed development rules that should not live in `AGENTS.md`.
 `AGENTS.md` stays a short navigation map.
 
+## Read Order Usage
+
+- The `AGENTS.md` Read Order is a list of documents to consult when relevant, not a checklist to read in full for every task.
+- Agents MUST always read `ARCHITECTURE.md` for structural context.
+- Agents MUST read this file (`development-rules.md`), `docs/generated/code-map.md`, and the relevant `docs/module-contracts/` files only when adding, refactoring, or removing code or modules.
+- Agents MAY skip the code map and module contracts for documentation-only tasks, configuration tweaks, or scoped bug fixes that do not change module boundaries or public surfaces.
+
 ## Code Discovery
 
 - Agents MUST search existing modules, components, scripts, styles, tests, generated files, and configuration before adding new code.

starter-kit/CLAUDE.md

@@ -13,8 +13,15 @@ Review project goals, priorities, and constraints before starting work.
 3. `docs/product-specs/index.md`
 4. `docs/exec-plans/active/`
 
+## Reference Map
+
+- Development rules: `docs/references/development-rules.md`
+- Code surface index: `docs/generated/code-map.md`
+- Module contracts: `docs/module-contracts/README.md`
+
 ## Working Rules
 
 - Always reflect TODO status in the active execution plan under `docs/exec-plans/active/`.
 - Update `docs/design-docs/` when a design decision or rationale changes.
+- Consult the code map and relevant module contract before adding new files or modules.
 - Split code changes into testable units.

starter-kit/docs/references/development-rules.md

@@ -3,6 +3,13 @@
 This document holds detailed development rules that should not live in `AGENTS.md`.
 `AGENTS.md` stays a short navigation map.
 
+## Read Order Usage
+
+- The `AGENTS.md` Read Order is a list of documents to consult when relevant, not a checklist to read in full for every task.
+- Agents MUST always read `ARCHITECTURE.md` for structural context.
+- Agents MUST read this file (`development-rules.md`), `docs/generated/code-map.md`, and the relevant `docs/module-contracts/` files only when adding, refactoring, or removing code or modules.
+- Agents MAY skip the code map and module contracts for documentation-only tasks, configuration tweaks, or scoped bug fixes that do not change module boundaries or public surfaces.
+
 ## Code Discovery
 
 - Agents MUST search existing modules, components, scripts, styles, tests, generated files, and configuration before adding new code.

targets/antigravity/harness-init/SKILL.md

@@ -48,7 +48,7 @@ Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder
 - Generate detailed design notes under `docs/design-docs/` only when they are justified by the project.
 - When generating `docs/PLANS.md`, follow the structure encouraged by the OpenAI Codex exec-plans article.
 - Generate optional documents according to the condition table in `references/templates.md` — each optional document has an explicit condition; generate it only when that condition is met.
-- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules.
+- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules. Do NOT generate a contract for small, single-file, or short-lived modules; treat the contract as documentation overhead that pays off only for durable, multi-file surfaces.
 - Populate `docs/generated/code-map.md` with concise entries for important features, modules, scripts, infra entry points, shared utilities, styling surfaces, tests, and generated artifacts.
 - If `referenceTools` is present, generate one `docs/references/<tool>-llms.txt` per tool.
 - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`.

targets/antigravity/harness-init/references/templates.md

@@ -32,7 +32,7 @@ Generate each document only when its stated condition is met:
 | `docs/SECURITY.md` | Authentication, authorization, or RLS is a core constraint |
 | `docs/RELIABILITY.md` | Availability, resource limits, or fault tolerance matter (free-tier infra, SLAs, uptime targets) |
 | `docs/generated/db-schema.md` | A database schema is described or implied |
-| `docs/module-contracts/<module>.md` | A module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules |
+| `docs/module-contracts/<module>.md` | A durable, multi-file module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules; skip for small, single-file, or short-lived modules |
 | `docs/exec-plans/active/EP-xxxx.md` | At least one in-progress task maps to an execution plan |
 | `docs/exec-plans/completed/EP-xxxx.md` | A previously completed execution plan exists |
 | `docs/product-specs/<feature>.md` | A concrete feature with scope, constraints, and done-when criteria is described |
@@ -342,6 +342,13 @@ Include concise commands, constraints, and known pitfalls.
 This document holds detailed development rules that should not live in `AGENTS.md`.
 `AGENTS.md` stays a short navigation map.
 
+## Read Order Usage
+
+- The `AGENTS.md` Read Order is a list of documents to consult when relevant, not a checklist to read in full for every task.
+- Agents MUST always read `ARCHITECTURE.md` for structural context.
+- Agents MUST read this file (`development-rules.md`), `docs/generated/code-map.md`, and the relevant `docs/module-contracts/` files only when adding, refactoring, or removing code or modules.
+- Agents MAY skip the code map and module contracts for documentation-only tasks, configuration tweaks, or scoped bug fixes that do not change module boundaries or public surfaces.
+
 ## Code Discovery
 
 - Agents MUST search existing modules, components, scripts, styles, tests, generated files, and configuration before adding new code.

targets/claude-code/harness-init/SKILL.md

@@ -48,7 +48,7 @@ Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder
 - Generate detailed design notes under `docs/design-docs/` only when they are justified by the project.
 - When generating `docs/PLANS.md`, follow the structure encouraged by the OpenAI Codex exec-plans article.
 - Generate optional documents according to the condition table in `references/templates.md` — each optional document has an explicit condition; generate it only when that condition is met.
-- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules.
+- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules. Do NOT generate a contract for small, single-file, or short-lived modules; treat the contract as documentation overhead that pays off only for durable, multi-file surfaces.
 - Populate `docs/generated/code-map.md` with concise entries for important features, modules, scripts, infra entry points, shared utilities, styling surfaces, tests, and generated artifacts.
 - If `referenceTools` is present, generate one `docs/references/<tool>-llms.txt` per tool.
 - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`.

targets/claude-code/harness-init/references/templates.md

@@ -32,7 +32,7 @@ Generate each document only when its stated condition is met:
 | `docs/SECURITY.md` | Authentication, authorization, or RLS is a core constraint |
 | `docs/RELIABILITY.md` | Availability, resource limits, or fault tolerance matter (free-tier infra, SLAs, uptime targets) |
 | `docs/generated/db-schema.md` | A database schema is described or implied |
-| `docs/module-contracts/<module>.md` | A module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules |
+| `docs/module-contracts/<module>.md` | A durable, multi-file module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules; skip for small, single-file, or short-lived modules |
 | `docs/exec-plans/active/EP-xxxx.md` | At least one in-progress task maps to an execution plan |
 | `docs/exec-plans/completed/EP-xxxx.md` | A previously completed execution plan exists |
 | `docs/product-specs/<feature>.md` | A concrete feature with scope, constraints, and done-when criteria is described |
@@ -342,6 +342,13 @@ Include concise commands, constraints, and known pitfalls.
 This document holds detailed development rules that should not live in `AGENTS.md`.
 `AGENTS.md` stays a short navigation map.
 
+## Read Order Usage
+
+- The `AGENTS.md` Read Order is a list of documents to consult when relevant, not a checklist to read in full for every task.
+- Agents MUST always read `ARCHITECTURE.md` for structural context.
+- Agents MUST read this file (`development-rules.md`), `docs/generated/code-map.md`, and the relevant `docs/module-contracts/` files only when adding, refactoring, or removing code or modules.
+- Agents MAY skip the code map and module contracts for documentation-only tasks, configuration tweaks, or scoped bug fixes that do not change module boundaries or public surfaces.
+
 ## Code Discovery
 
 - Agents MUST search existing modules, components, scripts, styles, tests, generated files, and configuration before adding new code.

targets/claude/harness-init/SKILL.md

@@ -48,7 +48,7 @@ Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder
 - Generate detailed design notes under `docs/design-docs/` only when they are justified by the project.
 - When generating `docs/PLANS.md`, follow the structure encouraged by the OpenAI Codex exec-plans article.
 - Generate optional documents according to the condition table in `references/templates.md` — each optional document has an explicit condition; generate it only when that condition is met.
-- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules.
+- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules. Do NOT generate a contract for small, single-file, or short-lived modules; treat the contract as documentation overhead that pays off only for durable, multi-file surfaces.
 - Populate `docs/generated/code-map.md` with concise entries for important features, modules, scripts, infra entry points, shared utilities, styling surfaces, tests, and generated artifacts.
 - If `referenceTools` is present, generate one `docs/references/<tool>-llms.txt` per tool.
 - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`.

targets/claude/harness-init/references/templates.md

@@ -32,7 +32,7 @@ Generate each document only when its stated condition is met:
 | `docs/SECURITY.md` | Authentication, authorization, or RLS is a core constraint |
 | `docs/RELIABILITY.md` | Availability, resource limits, or fault tolerance matter (free-tier infra, SLAs, uptime targets) |
 | `docs/generated/db-schema.md` | A database schema is described or implied |
-| `docs/module-contracts/<module>.md` | A module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules |
+| `docs/module-contracts/<module>.md` | A durable, multi-file module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules; skip for small, single-file, or short-lived modules |
 | `docs/exec-plans/active/EP-xxxx.md` | At least one in-progress task maps to an execution plan |
 | `docs/exec-plans/completed/EP-xxxx.md` | A previously completed execution plan exists |
 | `docs/product-specs/<feature>.md` | A concrete feature with scope, constraints, and done-when criteria is described |
@@ -342,6 +342,13 @@ Include concise commands, constraints, and known pitfalls.
 This document holds detailed development rules that should not live in `AGENTS.md`.
 `AGENTS.md` stays a short navigation map.
 
+## Read Order Usage
+
+- The `AGENTS.md` Read Order is a list of documents to consult when relevant, not a checklist to read in full for every task.
+- Agents MUST always read `ARCHITECTURE.md` for structural context.
+- Agents MUST read this file (`development-rules.md`), `docs/generated/code-map.md`, and the relevant `docs/module-contracts/` files only when adding, refactoring, or removing code or modules.
+- Agents MAY skip the code map and module contracts for documentation-only tasks, configuration tweaks, or scoped bug fixes that do not change module boundaries or public surfaces.
+
 ## Code Discovery
 
 - Agents MUST search existing modules, components, scripts, styles, tests, generated files, and configuration before adding new code.

targets/codex/harness-init/SKILL.md

@@ -48,7 +48,7 @@ Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder
 - Generate detailed design notes under `docs/design-docs/` only when they are justified by the project.
 - When generating `docs/PLANS.md`, follow the structure encouraged by the OpenAI Codex exec-plans article.
 - Generate optional documents according to the condition table in `references/templates.md` — each optional document has an explicit condition; generate it only when that condition is met.
-- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules.
+- Generate `docs/module-contracts/<module>.md` when a module, feature, package, service, infrastructure area, or script suite has explicit ownership, public entry points, or non-obvious reuse rules. Do NOT generate a contract for small, single-file, or short-lived modules; treat the contract as documentation overhead that pays off only for durable, multi-file surfaces.
 - Populate `docs/generated/code-map.md` with concise entries for important features, modules, scripts, infra entry points, shared utilities, styling surfaces, tests, and generated artifacts.
 - If `referenceTools` is present, generate one `docs/references/<tool>-llms.txt` per tool.
 - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`.