From 1e4925d089ca22b6779c47197e5db92a94249249 Mon Sep 17 00:00:00 2001 From: Austin Date: Thu, 14 May 2026 12:39:54 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20=EC=BD=94=EB=93=9C=20=EC=A1=B0?= =?UTF-8?q?=EC=A7=81=20=EA=B3=84=EC=95=BD=20=ED=9B=84=EC=86=8D=20=EC=A0=95?= =?UTF-8?q?=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 모듈 컨트랙트 트리거를 좁혀 단일 파일·일회성 모듈은 생성하지 않도록 명시. - code-organization-contract.md에 Authority 섹션을 추가해 module contract가 source-of-truth, code-map은 derived index임을 명시. - starter-kit/CLAUDE.md에 Reference Map과 코드맵·컨트랙트 우선 참조 규칙을 추가. - development-rules.md에 Read Order Usage 섹션을 추가해 code-map과 module contract가 코드 변경 시점에만 필수임을 명시. - skill/ 변경을 sync-skill-targets.sh로 5개 runtime bundle에 동기화. --- README.md | 2 +- docs/design-docs/code-organization-contract.md | 4 ++++ docs/references/development-rules.md | 7 +++++++ skill/SKILL.md | 2 +- skill/references/templates.md | 9 ++++++++- starter-kit/CLAUDE.md | 7 +++++++ starter-kit/docs/references/development-rules.md | 7 +++++++ targets/antigravity/harness-init/SKILL.md | 2 +- targets/antigravity/harness-init/references/templates.md | 9 ++++++++- targets/claude-code/harness-init/SKILL.md | 2 +- targets/claude-code/harness-init/references/templates.md | 9 ++++++++- targets/claude/harness-init/SKILL.md | 2 +- targets/claude/harness-init/references/templates.md | 9 ++++++++- targets/codex/harness-init/SKILL.md | 2 +- targets/codex/harness-init/references/templates.md | 9 ++++++++- targets/opencode/harness-init/SKILL.md | 2 +- targets/opencode/harness-init/references/templates.md | 9 ++++++++- 17 files changed, 80 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 35310ce..3b8ec7c 100644 --- a/README.md +++ b/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/.md` | 기능, 패키지, 서비스, 인프라 영역, 스크립트 묶음에 명확한 소유권이 있을 때 | +| `docs/module-contracts/.md` | 다중 파일·장기 유지되는 기능, 패키지, 서비스, 인프라 영역, 스크립트 묶음에 명확한 소유권이 있을 때 (단일 파일·일회성 모듈은 생성하지 않음) | | `docs/exec-plans/active/EP-xxxx.md` | 현재 진행 중인 실행 계획이 있을 때 | | `docs/product-specs/.md` | 구체적인 기능 스펙이 있을 때 | | `docs/DESIGN.md` | 별도로 정리할 설계 결정이 있을 때 | diff --git a/docs/design-docs/code-organization-contract.md b/docs/design-docs/code-organization-contract.md index 30a5cb0..48868ed 100644 --- a/docs/design-docs/code-organization-contract.md +++ b/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/.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. diff --git a/docs/references/development-rules.md b/docs/references/development-rules.md index 3bf0b9a..1257615 100644 --- a/docs/references/development-rules.md +++ b/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. diff --git a/skill/SKILL.md b/skill/SKILL.md index 3d54bc4..a3a4c51 100644 --- a/skill/SKILL.md +++ b/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/.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/.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/-llms.txt` per tool. - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`. diff --git a/skill/references/templates.md b/skill/references/templates.md index 96883da..3994d22 100644 --- a/skill/references/templates.md +++ b/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/.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/.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/.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. diff --git a/starter-kit/CLAUDE.md b/starter-kit/CLAUDE.md index 139c87c..10072b9 100644 --- a/starter-kit/CLAUDE.md +++ b/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. diff --git a/starter-kit/docs/references/development-rules.md b/starter-kit/docs/references/development-rules.md index 3bf0b9a..1257615 100644 --- a/starter-kit/docs/references/development-rules.md +++ b/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. diff --git a/targets/antigravity/harness-init/SKILL.md b/targets/antigravity/harness-init/SKILL.md index 3d54bc4..a3a4c51 100644 --- a/targets/antigravity/harness-init/SKILL.md +++ b/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/.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/.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/-llms.txt` per tool. - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`. diff --git a/targets/antigravity/harness-init/references/templates.md b/targets/antigravity/harness-init/references/templates.md index 96883da..3994d22 100644 --- a/targets/antigravity/harness-init/references/templates.md +++ b/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/.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/.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/.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. diff --git a/targets/claude-code/harness-init/SKILL.md b/targets/claude-code/harness-init/SKILL.md index 3d54bc4..a3a4c51 100644 --- a/targets/claude-code/harness-init/SKILL.md +++ b/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/.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/.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/-llms.txt` per tool. - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`. diff --git a/targets/claude-code/harness-init/references/templates.md b/targets/claude-code/harness-init/references/templates.md index 96883da..3994d22 100644 --- a/targets/claude-code/harness-init/references/templates.md +++ b/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/.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/.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/.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. diff --git a/targets/claude/harness-init/SKILL.md b/targets/claude/harness-init/SKILL.md index 3d54bc4..a3a4c51 100644 --- a/targets/claude/harness-init/SKILL.md +++ b/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/.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/.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/-llms.txt` per tool. - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`. diff --git a/targets/claude/harness-init/references/templates.md b/targets/claude/harness-init/references/templates.md index 96883da..3994d22 100644 --- a/targets/claude/harness-init/references/templates.md +++ b/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/.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/.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/.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. diff --git a/targets/codex/harness-init/SKILL.md b/targets/codex/harness-init/SKILL.md index 3d54bc4..a3a4c51 100644 --- a/targets/codex/harness-init/SKILL.md +++ b/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/.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/.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/-llms.txt` per tool. - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`. diff --git a/targets/codex/harness-init/references/templates.md b/targets/codex/harness-init/references/templates.md index 96883da..3994d22 100644 --- a/targets/codex/harness-init/references/templates.md +++ b/targets/codex/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/.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/.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/.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. diff --git a/targets/opencode/harness-init/SKILL.md b/targets/opencode/harness-init/SKILL.md index 3d54bc4..a3a4c51 100644 --- a/targets/opencode/harness-init/SKILL.md +++ b/targets/opencode/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/.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/.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/-llms.txt` per tool. - If `referenceTools` resolves to the fallback placeholder value, generate a single `docs/references/stack-reference-llms.txt`. diff --git a/targets/opencode/harness-init/references/templates.md b/targets/opencode/harness-init/references/templates.md index 96883da..3994d22 100644 --- a/targets/opencode/harness-init/references/templates.md +++ b/targets/opencode/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/.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/.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/.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.