diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 387bfad..16b8eac 100644 --- 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 index 67f3d96..670118a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,10 +6,13 @@ 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 @@ -17,10 +20,14 @@ This document is the primary agent entry point for this repository. - `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 index bba0f97..eb5d134 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -18,10 +18,13 @@ 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 @@ -29,6 +32,9 @@ The top-level subsystems are: - `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,6 +45,8 @@ 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. @@ -46,6 +54,7 @@ The top-level subsystems are: - 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 index 8cfb2d2..3b8ec7c 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,10 @@ 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` | 클론 후 빈 폴더 구조를 복원하는 스크립트 | @@ -84,10 +87,13 @@ Use the harness-init skill to scaffold the project operating documents. | 파일 | 생성 조건 | | --- | --- | +| `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/.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 new file mode 100644 index 0000000..48868ed --- /dev/null +++ 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/.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 index e6823a9..d2f6e65 100644 --- 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 new file mode 100644 index 0000000..d9593cc --- /dev/null +++ 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 new file mode 100644 index 0000000..277c290 --- /dev/null +++ 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 new file mode 100644 index 0000000..1980969 --- /dev/null +++ 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 new file mode 100644 index 0000000..875f52a --- /dev/null +++ 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//`. 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 new file mode 100644 index 0000000..009fb77 --- /dev/null +++ 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 new file mode 100644 index 0000000..cfe562b --- /dev/null +++ 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//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. diff --git a/docs/references/development-rules.md b/docs/references/development-rules.md new file mode 100644 index 0000000..1257615 --- /dev/null +++ b/docs/references/development-rules.md @@ -0,0 +1,40 @@ +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. diff --git a/docs/references/harness-engineering.md b/docs/references/harness-engineering.md index 6aeb21f..8f8e306 100644 --- a/docs/references/harness-engineering.md +++ b/docs/references/harness-engineering.md @@ -8,8 +8,10 @@ This document summarizes the core principles used when generating a harness-engi 2. Entry-point documents should define execution rules and reading order clearly. 3. Execution-plan documents should track TODO items explicitly. 4. Templates and automation code should share the same structure contract. -5. Human-facing setup and usage guidance belongs in `README.md`, while agent navigation rules belong in `AGENTS.md`. -6. `README.md` may follow the user's language, but every other generated document should be written in English. +5. Code organization context should cover frontend, backend, infra, scripts, tests, shared packages, generated artifacts, styles, and configuration. +6. Agents should be able to find existing reusable surfaces before adding new files or modules. +7. Human-facing setup and usage guidance belongs in `README.md`, while agent navigation rules belong in `AGENTS.md`. +8. `README.md` may follow the user's language, but every other generated document should be written in English. ## Minimal Contract @@ -19,7 +21,10 @@ The minimum harness contract includes: - `ARCHITECTURE.md` - `docs/design-docs/` - `docs/exec-plans/` +- `docs/generated/code-map.md` +- `docs/module-contracts/` - `docs/product-specs/` +- `docs/references/development-rules.md` - `docs/references/` - `scripts/init.sh` @@ -36,6 +41,7 @@ Generators should accept at least the following inputs: - reference tools - done-when criteria - required existing context +- major code areas that need module contracts Generators should produce at least the following outputs: @@ -44,5 +50,7 @@ Generators should produce at least the following outputs: - a project-specific `ARCHITECTURE.md` - an optional `CLAUDE.md` - the required `docs/` core set +- a code map for reusable frontend, backend, infra, scripts, shared, style, test, and generated surfaces +- a module-contract index and optional module-specific contracts - optional project-specific docs - an initialization script diff --git a/docs/superpowers/plans/2026-04-24-skill-eval-loop.md b/docs/superpowers/plans/2026-04-24-skill-eval-loop.md index 1b2324a..f3c4dbe 100644 --- a/docs/superpowers/plans/2026-04-24-skill-eval-loop.md +++ b/docs/superpowers/plans/2026-04-24-skill-eval-loop.md @@ -66,7 +66,8 @@ Create `tests/fixtures/interview.json`: "coreConstraints": "No PII leaks, all mutations traced via request-id", "referenceTools": "fastify, prisma, postgres", "doneWhen": "Orders can be created, read, reserved, and shipped via API.", - "projectContext": "Existing repo with legacy `lib/` that must stay compatible." + "projectContext": "Existing repo with legacy `lib/` that must stay compatible.", + "moduleContractAreas": "API routes, order services, inventory repository, shipping worker, deployment workflows, shared validation." } ``` @@ -106,7 +107,7 @@ You are operating inside an empty sandbox project directory. The `harness-init` Your task: 1. Load the `harness-init` skill from `.claude/skills/harness-init/SKILL.md`. -2. Treat the JSON object appended at the end of this prompt as the user's answers to the ten interview questions defined in the skill. The JSON keys map 1:1 to the question subjects in `SKILL.md` (`projectName`, `projectDescription`, `techStack`, `teamSize`, `agentsInUse`, `primaryWorkflows`, `coreConstraints`, `referenceTools`, `doneWhen`, `projectContext`). +2. Treat the JSON object appended at the end of this prompt as the user's answers to the eleven interview questions defined in the skill. The JSON keys map 1:1 to the question subjects in `SKILL.md` (`projectName`, `projectDescription`, `techStack`, `teamSize`, `agentsInUse`, `primaryWorkflows`, `coreConstraints`, `referenceTools`, `doneWhen`, `projectContext`, `moduleContractAreas`). 3. Execute every generation rule in `SKILL.md` using those answers. 4. Write all generated files into the current working directory. 5. Do not ask clarifying questions. Do not pause for confirmation. Do not modify files under `.claude/`. @@ -155,7 +156,7 @@ Emit a report in Markdown. The very first line MUST be a summary line of exactly SUMMARY: / hard checks passed; subagent-score /5 ``` -Where `` is the count of `[PASS]` items, `` is 8, and `` is the arithmetic mean of the four subagent-delegation scores rounded to one decimal. +Where `` is the count of `[PASS]` items, `` is 10, and `` is the arithmetic mean of the four subagent-delegation scores rounded to one decimal. Then produce the two sections below. @@ -168,20 +169,22 @@ Items to evaluate (in this order): 1. Root `README.md`, `AGENTS.md`, and `ARCHITECTURE.md` all exist in the generated tree and are non-empty. 2. `AGENTS.md` contains both an explicit read order and a repository map. 3. `ARCHITECTURE.md` follows matklad's system-map style, with sections for high-level overview, code map by directory, and cross-cutting concerns. -4. All four harness core docs exist: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, `docs/product-specs/index.md`. -5. At least one file matching `docs/references/*-llms.txt` exists and is non-empty. -6. `scripts/init.sh` exists. -7. The `doneWhen` / acceptance criteria supplied in the interview answers is reflected both in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. -8. Cross-document Markdown links inside the generated tree use relative paths and every such link resolves to a file that exists in the tree. +4. All seven harness core docs exist: `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`. +5. `docs/generated/code-map.md` covers at least frontend, backend, infra, scripts, shared code, styles, tests, generated artifacts, or the generated project's equivalent code areas. +6. `AGENTS.md` stays under 100 lines, acts as a navigation map, and points to `docs/references/development-rules.md` for detailed development rules. +7. At least one file matching `docs/references/*-llms.txt` exists and is non-empty. +8. `scripts/init.sh` exists. +9. The `doneWhen` / acceptance criteria supplied in the interview answers is reflected both in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. +10. Cross-document Markdown links inside the generated tree use relative paths and every such link resolves to a file that exists in the tree. ## Subagent-Delegation Rubric For each of the four axes below, assign an integer score from 1 to 5 and write one paragraph of justification. Do NOT use `[PASS]` or `[FAIL]` markers in this section. - Onboarding clarity: could a subagent pick up work using only these docs? -- Boundary isolation: are modules and responsibilities distinct enough to split work across subagents? +- Boundary isolation: are modules, files, and responsibilities distinct enough to split work across subagents? - Decision traceability: are constraints and rationale captured in design docs rather than scattered or missing? -- Actionability: is there a clear first next step a subagent could take, evidenced by the tech-debt tracker or exec-plans content? +- Actionability: is there a clear first next step and a clear existing-code reuse path a subagent could take, evidenced by the code map, tech-debt tracker, or exec-plans content? --- @@ -200,7 +203,7 @@ git add tests/judge-rubric.md git commit -m "$(cat <<'EOF' feat: Judge 루브릭 추가 -- tests/judge-rubric.md에 서브에이전트 위임 관점의 하드 체크리스트 8항목과 질적 평가 4축(5점 척도)을 명시한다. +- tests/judge-rubric.md에 서브에이전트 위임 관점의 하드 체크리스트 10항목과 질적 평가 4축(5점 척도)을 명시한다. - 응답 첫 줄 SUMMARY 포맷과 [PASS]/[FAIL] 사용 범위 제약을 계약으로 고정해 오케스트레이터의 exit-code 파싱이 깨지지 않도록 한다. EOF )" @@ -625,7 +628,7 @@ echo "$LATEST" head -20 "$LATEST/report.md" ``` -Expected: the first line of `report.md` matches `^SUMMARY: [0-9]+/8 hard checks passed; subagent-score [0-9.]+/5$`. +Expected: the first line of `report.md` matches `^SUMMARY: [0-9]+/10 hard checks passed; subagent-score [0-9.]+/5$`. - [ ] **Step 3: Sanity-check the generated tree** @@ -672,6 +675,6 @@ Spec coverage: - `.github/workflows/ci.yml` change — Task 5. - End-to-end smoke validation — Task 8. -Type consistency: the rubric's `SUMMARY: /` contract is referenced only in Task 3 and Task 8; totals match (8 hard checks, 4 subagent axes). `[FAIL]` marker is used in Task 7's exit-gate grep and Task 3's rubric constraint; consistent. +Type consistency: the rubric's `SUMMARY: /` contract is referenced only in Task 3 and Task 8; totals match (10 hard checks, 4 subagent axes). `[FAIL]` marker is used in Task 7's exit-gate grep and Task 3's rubric constraint; consistent. Placeholders: none — every code block is complete. The only "open" moment is Task 8 Step 4, which depends on the live run and is necessarily conditional. diff --git a/docs/superpowers/specs/2026-04-24-skill-eval-loop-design.md b/docs/superpowers/specs/2026-04-24-skill-eval-loop-design.md index 5d9cd9a..90bfaca 100644 --- a/docs/superpowers/specs/2026-04-24-skill-eval-loop-design.md +++ b/docs/superpowers/specs/2026-04-24-skill-eval-loop-design.md @@ -119,7 +119,7 @@ Purpose: orchestrate Run phase, Judge phase, report capture, cleanup. Inputs: -- `tests/fixtures/interview.json` (answers to the ten interview questions) +- `tests/fixtures/interview.json` (answers to the eleven interview questions) - `tests/prompts/run.md` (Run-phase instruction) - `tests/judge-rubric.md` (judge prompt and checklist) - `targets/claude-code/harness-init/` (bundle to exercise) @@ -198,7 +198,7 @@ Design points: ### `tests/fixtures/interview.json` -Holds one canonical set of answers for the ten questions in `SKILL.md`. +Holds one canonical set of answers for the eleven questions in `SKILL.md`. JSON keeps the file diffable when we revise. Example shape: ```json @@ -212,7 +212,8 @@ JSON keeps the file diffable when we revise. Example shape: "coreConstraints": "No PII leaks, all mutations traced via request-id", "referenceTools": "fastify, prisma, postgres", "doneWhen": "Orders can be created, read, reserved, and shipped via API.", - "projectContext": "Existing repo with legacy `lib/` that must stay compatible." + "projectContext": "Existing repo with legacy `lib/` that must stay compatible.", + "moduleContractAreas": "API routes, order services, inventory repository, shipping worker, deployment workflows, shared validation." } ``` @@ -223,7 +224,7 @@ formatting them into the interview exchange expected by `SKILL.md`. Static instruction file the Run phase feeds to `claude -p`. It tells the model: load the `harness-init` skill, treat the following JSON object as -the ten interview answers, execute the skill's generation rules, and +the eleven interview answers, execute the skill's generation rules, and write the output files into the current directory. This file is short and committed to the repo so that what the Run phase instructs is always reviewable without reading shell. @@ -248,8 +249,16 @@ The rubric has two sections. - `ARCHITECTURE.md` follows matklad's system-map style (sections for overview, code map, and cross-cutting concerns). - `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, - `docs/exec-plans/tech-debt-tracker.md`, `docs/product-specs/index.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` all exist. + - `docs/generated/code-map.md` covers the generated project's important + code areas, including frontend, backend, infra, scripts, shared code, + styles, tests, generated artifacts, or equivalent areas. + - `AGENTS.md` stays under 100 lines, acts as a navigation map, and + points to `docs/references/development-rules.md` for detailed + development rules. - At least one `docs/references/*-llms.txt` exists. - `scripts/init.sh` exists and is executable. - `doneWhen` from the fixture is reflected in `AGENTS.md` and in at @@ -263,12 +272,13 @@ The rubric has two sections. - Onboarding clarity: could a subagent pick up work using only these docs? - - Boundary isolation: are modules and responsibilities distinct enough + - Boundary isolation: are modules, files, and responsibilities distinct enough to split work? - Decision traceability: are constraints and rationale captured in design docs rather than scattered or missing? - - Actionability: is there a clear first next step a subagent could - take, evidenced by the tech-debt tracker or exec-plans content? + - Actionability: is there a clear first next step and existing-code reuse + path a subagent could take, evidenced by the code map, tech-debt + tracker, or exec-plans content? Note: v1 intentionally omits any direct comparison to `starter-kit/`. The judge evaluates only the generated tree against intrinsic criteria. diff --git a/scripts/check-agents-doc.sh b/scripts/check-agents-doc.sh new file mode 100755 index 0000000..217b3cd --- /dev/null +++ b/scripts/check-agents-doc.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +set -euo pipefail + +: ' +check-agents-doc.sh + +Validates that every AGENTS.md acting as a navigation map stays under the +documented line limit so it does not drift into a full development manual. +Exits non-zero on the first violation with a clear message. +' + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +: ' +MAX_LINES is the maximum line count enforced for AGENTS.md navigation maps. +' +MAX_LINES=100 + +: ' +AGENTS_MD_FILES lists every AGENTS.md tracked by this repository that must +stay within MAX_LINES. +' +AGENTS_MD_FILES=( + "AGENTS.md" + "starter-kit/AGENTS.md" +) + +fail() { + echo "[check-agents-doc] FAIL: $1" >&2 + exit 1 +} + +check_file() { + local rel="$1" + local path="$ROOT_DIR/$rel" + local lines + + [[ -f "$path" ]] || fail "missing AGENTS.md: $rel" + + lines="$(wc -l < "$path" | tr -d ' ')" + if (( lines > MAX_LINES )); then + fail "$rel has $lines lines, exceeds $MAX_LINES-line navigation map limit" + fi + + echo "[check-agents-doc] PASS: $rel ($lines lines)" +} + +for rel in "${AGENTS_MD_FILES[@]}"; do + check_file "$rel" +done + +echo "[check-agents-doc] All AGENTS.md files within $MAX_LINES-line limit." diff --git a/skill/SKILL.md b/skill/SKILL.md index 1863825..a3a4c51 100644 --- a/skill/SKILL.md +++ b/skill/SKILL.md @@ -14,7 +14,7 @@ It is intended to be packaged for Claude, Claude Code, Codex, OpenCode, and Anti ## Interview Questions -Ask the following 10 questions in order: +Ask the following 11 questions in order: 1. Project name 2. Project description @@ -26,9 +26,10 @@ Ask the following 10 questions in order: 8. Which libraries or tools need `llms.txt` reference files? (for example: react, nextjs, prisma, uv, nixpacks) 9. What are the project's done-when or acceptance criteria? 10. Which existing files, folders, or documents must be referenced? +11. Which major code areas need explicit ownership or module contracts? (for example: frontend, backend, infra, scripts, shared packages) Treat a blank answer for question 8 as the fallback placeholder value `미정`. -Treat blank answers for questions 9 and 10 as the same fallback placeholder value. +Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder value. ## Generation Rules @@ -37,16 +38,23 @@ Treat blank answers for questions 9 and 10 as the same fallback placeholder valu - Write `AGENTS.md` as a document map, not a long manual. - Write `ARCHITECTURE.md` as the top-level structure document for the repository. - Generate `CLAUDE.md` when it is useful for the target project. -- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/product-specs/`, `docs/references/`. +- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/module-contracts/`, `docs/product-specs/`, `docs/references/`. - Use matklad's `ARCHITECTURE.md` style as the reference for the root `ARCHITECTURE.md`. -- Always create the harness core documents: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, and `docs/product-specs/index.md`. +- Always create the harness core 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`, and `docs/references/development-rules.md`. +- Treat code organization as a cross-cutting contract that applies to frontend, backend, infra, scripts, shared packages, generated code, tests, and configuration. +- Keep `AGENTS.md` as a navigation map under 100 lines. +- Add discovery, reuse, file-organization, and subagent handoff rules to `docs/references/development-rules.md` so agents search existing code before adding new modules or large files. +- Add module boundaries, public surfaces, ownership, dependency direction, and large-file split criteria to `ARCHITECTURE.md`. - 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. 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`. - Reflect `doneWhen` in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. - If `projectContext` is not the fallback placeholder value, reflect it in the `AGENTS.md` read order or repository map. +- If `moduleContractAreas` is not the fallback placeholder value, reflect it in `ARCHITECTURE.md`, `docs/generated/code-map.md`, and `docs/module-contracts/README.md`. - Keep installation, run, and usage instructions in `README.md`; keep agent navigation rules in `AGENTS.md`. - Generate `scripts/init.sh` to automate base directory initialization. - Write `README.md` in the user's language or the language explicitly requested for the README. diff --git a/skill/references/templates.md b/skill/references/templates.md index 46e004f..3994d22 100644 --- a/skill/references/templates.md +++ b/skill/references/templates.md @@ -14,7 +14,10 @@ Treat the following files as the core harness-engineering set: - `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` - at least one `docs/references/*-llms.txt` file ## Optional Docs @@ -23,10 +26,13 @@ Generate each document only when its stated condition is met: | File | Generate when... | | --- | --- | +| `docs/BACKEND.md` | A backend, API, worker, queue, service layer, or data-access layer is present | | `docs/FRONTEND.md` | A frontend tech stack is present (e.g., React, Vue, Next.js, SvelteKit) | +| `docs/INFRASTRUCTURE.md` | Deployment, hosting, IaC, CI/CD, observability, or runtime configuration is present | | `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 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 | @@ -58,16 +64,30 @@ If the input is blank or resolves to the fallback placeholder value, generate on ## Read Order 1. ARCHITECTURE.md -2. docs/product-specs/index.md -3. docs/exec-plans/active/ -4. docs/design-docs/ -5. docs/references/ +2. docs/references/development-rules.md +3. docs/generated/code-map.md +4. docs/module-contracts/README.md +5. docs/product-specs/index.md +6. docs/exec-plans/active/ +7. docs/design-docs/ +8. docs/references/ ## Repository Map - app/ - docs/ - scripts/ + +## Reference Map + +- Development rules: docs/references/development-rules.md +- Code surface index: docs/generated/code-map.md +- Module contracts: docs/module-contracts/README.md + +## Rules + +- Agents MUST treat this file as a map, not a full manual. +- Agents MUST keep this file under 100 lines. ``` ## README.md Template @@ -97,9 +117,104 @@ This document explains the stable structure of the repository. ## Module Boundaries +## Public Surfaces + +## Dependency Direction + +## File Organization + ## Invariants ``` +## docs/generated/code-map.md Template + +```markdown +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | +``` + +## docs/module-contracts/README.md Template + +```markdown +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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. +``` + +## docs/module-contracts/.md Template + +```markdown +# Module Contract + +## Responsibility + +[Describe what this module owns.] + +## Public Entry Points + +| Name | Kind | Purpose | Source | +| --- | --- | --- | --- | +| `[name]` | `[component, function, class, route, job, script, config]` | `[purpose]` | `[path]` | + +## Internal Reuse + +| Surface | Reuse When | Source | +| --- | --- | --- | +| `[surface]` | `[scenario]` | `[path]` | + +## File Organization + +[Describe the local folder and file naming rules.] + +## Dependency Rules + +[Describe allowed and forbidden dependencies.] + +## Styling Rules + +[Describe style ownership when the module has UI.] + +## Verification + +[List relevant tests, linters, build commands, and manual checks.] +``` + ## docs/design-docs/index.md Template ```markdown @@ -175,6 +290,43 @@ This document explains the stable structure of the repository. ## Done When ``` +## docs/BACKEND.md Template + +```markdown +# Backend + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +[Describe service, route, repository, validation, worker, and shared package boundaries.] + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +[Describe which services, repositories, validators, and clients must be reused before adding new ones.] + +## File Size Rules + +[Describe when routes, services, jobs, or data-access files must be split.] + +## Verification + +[Describe backend test, lint, typecheck, migration, and smoke-check commands.] +``` + ## docs/references/stack-reference-llms.txt Template ```text @@ -182,6 +334,51 @@ Reference for agents. Include concise commands, constraints, and known pitfalls. ``` +## docs/references/development-rules.md Template + +```markdown +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. +``` + ## docs/references/-llms.txt Template ```text @@ -245,11 +442,54 @@ Pitfalls [Directory layout] +## Styling Ownership + +[Describe where global styles, design tokens, CSS modules, component styles, and feature styles live.] + +## Reuse Rules + +[Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership.] + +## File Size Rules + +[Describe when components, pages, hooks, and stylesheets must be split.] + ## Performance Budget [Lighthouse targets and Core Web Vitals targets] ``` +## docs/INFRASTRUCTURE.md Template + +```markdown +# Infrastructure + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +[Describe environment variables, secret ownership, config files, and deployment settings.] + +## Reuse Rules + +[Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused.] + +## File Size Rules + +[Describe when workflow files, IaC modules, and deployment scripts must be split.] + +## Verification + +[Describe plan, validate, dry-run, CI, and rollback checks.] +``` + ## docs/SECURITY.md Template ```markdown @@ -378,5 +618,5 @@ Pitfalls #!/usr/bin/env bash set -euo pipefail -mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/product-specs docs/references scripts +mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/module-contracts docs/product-specs docs/references scripts ``` diff --git a/skill/runtime-guides/antigravity/PROMPT.md b/skill/runtime-guides/antigravity/PROMPT.md index 8187a0f..3ac996f 100644 --- a/skill/runtime-guides/antigravity/PROMPT.md +++ b/skill/runtime-guides/antigravity/PROMPT.md @@ -4,7 +4,7 @@ Use the `harness-init` workflow to scaffold a harness-engineering document set f ## Required Behavior -- Ask the canonical 10 interview questions from `SKILL.md` +- Ask the canonical 11 interview questions from `SKILL.md` - Generate `README.md`, `AGENTS.md`, `ARCHITECTURE.md`, and the harness core `docs/` set - Keep `README.md` in the user's language - Keep the remaining generated documents in English diff --git a/starter-kit/AGENTS.md b/starter-kit/AGENTS.md index 9c4f8bb..e482e77 100644 --- a/starter-kit/AGENTS.md +++ b/starter-kit/AGENTS.md @@ -1,28 +1,35 @@ # AGENTS.md Template -This template defines baseline rules for agent collaboration in a project repository. +This template defines the short navigation entry point for agent collaboration in a project repository. ## Scope These rules apply repository-wide unless a nested `AGENTS.md` provides stricter rules. -## Execution Rules +## Read Order -- Agents MUST treat this file as a map, not a full encyclopedia. -- Agents MUST read `ARCHITECTURE.md` before large structural changes. -- Agents MUST track TODO state in an active plan under `docs/exec-plans/active/`. -- Agents MUST update design decisions in `docs/design-docs/`. -- Agents SHOULD keep changes small and verifiable. -- Agents MAY propose alternative structures with explicit tradeoff notes. +1. `ARCHITECTURE.md` +2. `docs/references/development-rules.md` +3. `docs/generated/code-map.md` +4. `docs/module-contracts/README.md` +5. `docs/product-specs/index.md` +6. `docs/exec-plans/active/` +7. `docs/design-docs/` +8. `docs/references/` + +## Repository Map -## Documentation Rules +- `app/`: application runtime code +- `docs/`: product, architecture, execution, reference, and module-contract documents +- `scripts/`: repository automation -- External-facing modules MUST include clear documentation comments. -- Architectural decisions SHOULD be recorded with rationale and impact. -- Reference notes MAY be added under `docs/references/`. +## Reference Map -## Quality Rules +- Development rules: `docs/references/development-rules.md` +- Code surface index: `docs/generated/code-map.md` +- Module contracts: `docs/module-contracts/README.md` -- Scripts MUST fail fast on errors. -- CI checks SHOULD validate document links and architecture docs. -- Generated files MUST preserve existing user content when possible. +## Rules + +- Agents MUST treat this file as a map, not a full encyclopedia. +- Agents MUST keep this file under 100 lines. diff --git a/starter-kit/ARCHITECTURE.md b/starter-kit/ARCHITECTURE.md index 7b08513..17b99e2 100644 --- a/starter-kit/ARCHITECTURE.md +++ b/starter-kit/ARCHITECTURE.md @@ -10,6 +10,18 @@ Summarize domain boundaries, primary runtime components, and external dependenci Define module responsibilities and interface ownership. +## Public Surfaces + +List externally visible components, services, jobs, scripts, packages, infrastructure modules, and configuration entry points. + +## Dependency Direction + +Define which modules may depend on each other and which cross-boundary imports are forbidden. + +## File Organization + +Record naming conventions, co-location rules, generated-file ownership, and large-file split thresholds. + ## Invariants List structural constraints that must remain true as the project evolves. 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/BACKEND.md b/starter-kit/docs/BACKEND.md new file mode 100644 index 0000000..9e193be --- /dev/null +++ b/starter-kit/docs/BACKEND.md @@ -0,0 +1,34 @@ +# Backend + +Record backend runtime ownership, module boundaries, public entry points, and reuse rules. + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +Describe service, route, repository, validation, worker, and shared package boundaries. + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +Describe which services, repositories, validators, and clients must be reused before adding new ones. + +## File Size Rules + +Describe when routes, services, jobs, or data-access files must be split. + +## Verification + +Describe backend test, lint, typecheck, migration, and smoke-check commands. diff --git a/starter-kit/docs/FRONTEND.md b/starter-kit/docs/FRONTEND.md index 311a7f9..875b166 100644 --- a/starter-kit/docs/FRONTEND.md +++ b/starter-kit/docs/FRONTEND.md @@ -1,3 +1,42 @@ # Frontend Record frontend architecture and coding rules. + +## Stack + +| Concern | Choice | +| --- | --- | +| Framework | ... | +| Language | ... | +| Styling | ... | +| State | ... | + +## Rendering Model + +Describe server, client, static, and streaming rendering boundaries. + +## Data Fetching Conventions + +Describe how server and client data fetching are handled. + +## Component Organization + +Describe route, feature, shared UI, hook, state, test, and asset layout. + +## Styling Ownership + +Global CSS MUST be limited to design tokens, reset styles, base typography, and app-wide layout primitives. +Feature-specific styles MUST live with the feature or component that owns them. +Agents MUST NOT add unrelated component styles to a central stylesheet. + +## Reuse Rules + +Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership. + +## File Size Rules + +Describe when components, pages, hooks, and stylesheets must be split. + +## Performance Budget + +Record Lighthouse targets and Core Web Vitals targets. diff --git a/starter-kit/docs/INFRASTRUCTURE.md b/starter-kit/docs/INFRASTRUCTURE.md new file mode 100644 index 0000000..a9eebc9 --- /dev/null +++ b/starter-kit/docs/INFRASTRUCTURE.md @@ -0,0 +1,28 @@ +# Infrastructure + +Record deployment, hosting, IaC, CI/CD, observability, and runtime configuration ownership. + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +Describe environment variables, secret ownership, config files, and deployment settings. + +## Reuse Rules + +Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused. + +## File Size Rules + +Describe when workflow files, IaC modules, and deployment scripts must be split. + +## Verification + +Describe plan, validate, dry-run, CI, and rollback checks. diff --git a/starter-kit/docs/generated/code-map.md b/starter-kit/docs/generated/code-map.md new file mode 100644 index 0000000..222492e --- /dev/null +++ b/starter-kit/docs/generated/code-map.md @@ -0,0 +1,27 @@ +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | +| 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` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | diff --git a/starter-kit/docs/module-contracts/README.md b/starter-kit/docs/module-contracts/README.md new file mode 100644 index 0000000..9da38c5 --- /dev/null +++ b/starter-kit/docs/module-contracts/README.md @@ -0,0 +1,15 @@ +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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/starter-kit/docs/references/development-rules.md b/starter-kit/docs/references/development-rules.md new file mode 100644 index 0000000..1257615 --- /dev/null +++ b/starter-kit/docs/references/development-rules.md @@ -0,0 +1,40 @@ +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. diff --git a/targets/antigravity/harness-init/PROMPT.md b/targets/antigravity/harness-init/PROMPT.md index 8187a0f..3ac996f 100644 --- a/targets/antigravity/harness-init/PROMPT.md +++ b/targets/antigravity/harness-init/PROMPT.md @@ -4,7 +4,7 @@ Use the `harness-init` workflow to scaffold a harness-engineering document set f ## Required Behavior -- Ask the canonical 10 interview questions from `SKILL.md` +- Ask the canonical 11 interview questions from `SKILL.md` - Generate `README.md`, `AGENTS.md`, `ARCHITECTURE.md`, and the harness core `docs/` set - Keep `README.md` in the user's language - Keep the remaining generated documents in English diff --git a/targets/antigravity/harness-init/SKILL.md b/targets/antigravity/harness-init/SKILL.md index 1863825..a3a4c51 100644 --- a/targets/antigravity/harness-init/SKILL.md +++ b/targets/antigravity/harness-init/SKILL.md @@ -14,7 +14,7 @@ It is intended to be packaged for Claude, Claude Code, Codex, OpenCode, and Anti ## Interview Questions -Ask the following 10 questions in order: +Ask the following 11 questions in order: 1. Project name 2. Project description @@ -26,9 +26,10 @@ Ask the following 10 questions in order: 8. Which libraries or tools need `llms.txt` reference files? (for example: react, nextjs, prisma, uv, nixpacks) 9. What are the project's done-when or acceptance criteria? 10. Which existing files, folders, or documents must be referenced? +11. Which major code areas need explicit ownership or module contracts? (for example: frontend, backend, infra, scripts, shared packages) Treat a blank answer for question 8 as the fallback placeholder value `미정`. -Treat blank answers for questions 9 and 10 as the same fallback placeholder value. +Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder value. ## Generation Rules @@ -37,16 +38,23 @@ Treat blank answers for questions 9 and 10 as the same fallback placeholder valu - Write `AGENTS.md` as a document map, not a long manual. - Write `ARCHITECTURE.md` as the top-level structure document for the repository. - Generate `CLAUDE.md` when it is useful for the target project. -- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/product-specs/`, `docs/references/`. +- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/module-contracts/`, `docs/product-specs/`, `docs/references/`. - Use matklad's `ARCHITECTURE.md` style as the reference for the root `ARCHITECTURE.md`. -- Always create the harness core documents: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, and `docs/product-specs/index.md`. +- Always create the harness core 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`, and `docs/references/development-rules.md`. +- Treat code organization as a cross-cutting contract that applies to frontend, backend, infra, scripts, shared packages, generated code, tests, and configuration. +- Keep `AGENTS.md` as a navigation map under 100 lines. +- Add discovery, reuse, file-organization, and subagent handoff rules to `docs/references/development-rules.md` so agents search existing code before adding new modules or large files. +- Add module boundaries, public surfaces, ownership, dependency direction, and large-file split criteria to `ARCHITECTURE.md`. - 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. 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`. - Reflect `doneWhen` in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. - If `projectContext` is not the fallback placeholder value, reflect it in the `AGENTS.md` read order or repository map. +- If `moduleContractAreas` is not the fallback placeholder value, reflect it in `ARCHITECTURE.md`, `docs/generated/code-map.md`, and `docs/module-contracts/README.md`. - Keep installation, run, and usage instructions in `README.md`; keep agent navigation rules in `AGENTS.md`. - Generate `scripts/init.sh` to automate base directory initialization. - Write `README.md` in the user's language or the language explicitly requested for the README. diff --git a/targets/antigravity/harness-init/references/templates.md b/targets/antigravity/harness-init/references/templates.md index 46e004f..3994d22 100644 --- a/targets/antigravity/harness-init/references/templates.md +++ b/targets/antigravity/harness-init/references/templates.md @@ -14,7 +14,10 @@ Treat the following files as the core harness-engineering set: - `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` - at least one `docs/references/*-llms.txt` file ## Optional Docs @@ -23,10 +26,13 @@ Generate each document only when its stated condition is met: | File | Generate when... | | --- | --- | +| `docs/BACKEND.md` | A backend, API, worker, queue, service layer, or data-access layer is present | | `docs/FRONTEND.md` | A frontend tech stack is present (e.g., React, Vue, Next.js, SvelteKit) | +| `docs/INFRASTRUCTURE.md` | Deployment, hosting, IaC, CI/CD, observability, or runtime configuration is present | | `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 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 | @@ -58,16 +64,30 @@ If the input is blank or resolves to the fallback placeholder value, generate on ## Read Order 1. ARCHITECTURE.md -2. docs/product-specs/index.md -3. docs/exec-plans/active/ -4. docs/design-docs/ -5. docs/references/ +2. docs/references/development-rules.md +3. docs/generated/code-map.md +4. docs/module-contracts/README.md +5. docs/product-specs/index.md +6. docs/exec-plans/active/ +7. docs/design-docs/ +8. docs/references/ ## Repository Map - app/ - docs/ - scripts/ + +## Reference Map + +- Development rules: docs/references/development-rules.md +- Code surface index: docs/generated/code-map.md +- Module contracts: docs/module-contracts/README.md + +## Rules + +- Agents MUST treat this file as a map, not a full manual. +- Agents MUST keep this file under 100 lines. ``` ## README.md Template @@ -97,9 +117,104 @@ This document explains the stable structure of the repository. ## Module Boundaries +## Public Surfaces + +## Dependency Direction + +## File Organization + ## Invariants ``` +## docs/generated/code-map.md Template + +```markdown +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | +``` + +## docs/module-contracts/README.md Template + +```markdown +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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. +``` + +## docs/module-contracts/.md Template + +```markdown +# Module Contract + +## Responsibility + +[Describe what this module owns.] + +## Public Entry Points + +| Name | Kind | Purpose | Source | +| --- | --- | --- | --- | +| `[name]` | `[component, function, class, route, job, script, config]` | `[purpose]` | `[path]` | + +## Internal Reuse + +| Surface | Reuse When | Source | +| --- | --- | --- | +| `[surface]` | `[scenario]` | `[path]` | + +## File Organization + +[Describe the local folder and file naming rules.] + +## Dependency Rules + +[Describe allowed and forbidden dependencies.] + +## Styling Rules + +[Describe style ownership when the module has UI.] + +## Verification + +[List relevant tests, linters, build commands, and manual checks.] +``` + ## docs/design-docs/index.md Template ```markdown @@ -175,6 +290,43 @@ This document explains the stable structure of the repository. ## Done When ``` +## docs/BACKEND.md Template + +```markdown +# Backend + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +[Describe service, route, repository, validation, worker, and shared package boundaries.] + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +[Describe which services, repositories, validators, and clients must be reused before adding new ones.] + +## File Size Rules + +[Describe when routes, services, jobs, or data-access files must be split.] + +## Verification + +[Describe backend test, lint, typecheck, migration, and smoke-check commands.] +``` + ## docs/references/stack-reference-llms.txt Template ```text @@ -182,6 +334,51 @@ Reference for agents. Include concise commands, constraints, and known pitfalls. ``` +## docs/references/development-rules.md Template + +```markdown +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. +``` + ## docs/references/-llms.txt Template ```text @@ -245,11 +442,54 @@ Pitfalls [Directory layout] +## Styling Ownership + +[Describe where global styles, design tokens, CSS modules, component styles, and feature styles live.] + +## Reuse Rules + +[Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership.] + +## File Size Rules + +[Describe when components, pages, hooks, and stylesheets must be split.] + ## Performance Budget [Lighthouse targets and Core Web Vitals targets] ``` +## docs/INFRASTRUCTURE.md Template + +```markdown +# Infrastructure + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +[Describe environment variables, secret ownership, config files, and deployment settings.] + +## Reuse Rules + +[Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused.] + +## File Size Rules + +[Describe when workflow files, IaC modules, and deployment scripts must be split.] + +## Verification + +[Describe plan, validate, dry-run, CI, and rollback checks.] +``` + ## docs/SECURITY.md Template ```markdown @@ -378,5 +618,5 @@ Pitfalls #!/usr/bin/env bash set -euo pipefail -mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/product-specs docs/references scripts +mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/module-contracts docs/product-specs docs/references scripts ``` diff --git a/targets/claude-code/harness-init/SKILL.md b/targets/claude-code/harness-init/SKILL.md index 1863825..a3a4c51 100644 --- a/targets/claude-code/harness-init/SKILL.md +++ b/targets/claude-code/harness-init/SKILL.md @@ -14,7 +14,7 @@ It is intended to be packaged for Claude, Claude Code, Codex, OpenCode, and Anti ## Interview Questions -Ask the following 10 questions in order: +Ask the following 11 questions in order: 1. Project name 2. Project description @@ -26,9 +26,10 @@ Ask the following 10 questions in order: 8. Which libraries or tools need `llms.txt` reference files? (for example: react, nextjs, prisma, uv, nixpacks) 9. What are the project's done-when or acceptance criteria? 10. Which existing files, folders, or documents must be referenced? +11. Which major code areas need explicit ownership or module contracts? (for example: frontend, backend, infra, scripts, shared packages) Treat a blank answer for question 8 as the fallback placeholder value `미정`. -Treat blank answers for questions 9 and 10 as the same fallback placeholder value. +Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder value. ## Generation Rules @@ -37,16 +38,23 @@ Treat blank answers for questions 9 and 10 as the same fallback placeholder valu - Write `AGENTS.md` as a document map, not a long manual. - Write `ARCHITECTURE.md` as the top-level structure document for the repository. - Generate `CLAUDE.md` when it is useful for the target project. -- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/product-specs/`, `docs/references/`. +- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/module-contracts/`, `docs/product-specs/`, `docs/references/`. - Use matklad's `ARCHITECTURE.md` style as the reference for the root `ARCHITECTURE.md`. -- Always create the harness core documents: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, and `docs/product-specs/index.md`. +- Always create the harness core 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`, and `docs/references/development-rules.md`. +- Treat code organization as a cross-cutting contract that applies to frontend, backend, infra, scripts, shared packages, generated code, tests, and configuration. +- Keep `AGENTS.md` as a navigation map under 100 lines. +- Add discovery, reuse, file-organization, and subagent handoff rules to `docs/references/development-rules.md` so agents search existing code before adding new modules or large files. +- Add module boundaries, public surfaces, ownership, dependency direction, and large-file split criteria to `ARCHITECTURE.md`. - 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. 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`. - Reflect `doneWhen` in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. - If `projectContext` is not the fallback placeholder value, reflect it in the `AGENTS.md` read order or repository map. +- If `moduleContractAreas` is not the fallback placeholder value, reflect it in `ARCHITECTURE.md`, `docs/generated/code-map.md`, and `docs/module-contracts/README.md`. - Keep installation, run, and usage instructions in `README.md`; keep agent navigation rules in `AGENTS.md`. - Generate `scripts/init.sh` to automate base directory initialization. - Write `README.md` in the user's language or the language explicitly requested for the README. diff --git a/targets/claude-code/harness-init/references/templates.md b/targets/claude-code/harness-init/references/templates.md index 46e004f..3994d22 100644 --- a/targets/claude-code/harness-init/references/templates.md +++ b/targets/claude-code/harness-init/references/templates.md @@ -14,7 +14,10 @@ Treat the following files as the core harness-engineering set: - `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` - at least one `docs/references/*-llms.txt` file ## Optional Docs @@ -23,10 +26,13 @@ Generate each document only when its stated condition is met: | File | Generate when... | | --- | --- | +| `docs/BACKEND.md` | A backend, API, worker, queue, service layer, or data-access layer is present | | `docs/FRONTEND.md` | A frontend tech stack is present (e.g., React, Vue, Next.js, SvelteKit) | +| `docs/INFRASTRUCTURE.md` | Deployment, hosting, IaC, CI/CD, observability, or runtime configuration is present | | `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 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 | @@ -58,16 +64,30 @@ If the input is blank or resolves to the fallback placeholder value, generate on ## Read Order 1. ARCHITECTURE.md -2. docs/product-specs/index.md -3. docs/exec-plans/active/ -4. docs/design-docs/ -5. docs/references/ +2. docs/references/development-rules.md +3. docs/generated/code-map.md +4. docs/module-contracts/README.md +5. docs/product-specs/index.md +6. docs/exec-plans/active/ +7. docs/design-docs/ +8. docs/references/ ## Repository Map - app/ - docs/ - scripts/ + +## Reference Map + +- Development rules: docs/references/development-rules.md +- Code surface index: docs/generated/code-map.md +- Module contracts: docs/module-contracts/README.md + +## Rules + +- Agents MUST treat this file as a map, not a full manual. +- Agents MUST keep this file under 100 lines. ``` ## README.md Template @@ -97,9 +117,104 @@ This document explains the stable structure of the repository. ## Module Boundaries +## Public Surfaces + +## Dependency Direction + +## File Organization + ## Invariants ``` +## docs/generated/code-map.md Template + +```markdown +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | +``` + +## docs/module-contracts/README.md Template + +```markdown +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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. +``` + +## docs/module-contracts/.md Template + +```markdown +# Module Contract + +## Responsibility + +[Describe what this module owns.] + +## Public Entry Points + +| Name | Kind | Purpose | Source | +| --- | --- | --- | --- | +| `[name]` | `[component, function, class, route, job, script, config]` | `[purpose]` | `[path]` | + +## Internal Reuse + +| Surface | Reuse When | Source | +| --- | --- | --- | +| `[surface]` | `[scenario]` | `[path]` | + +## File Organization + +[Describe the local folder and file naming rules.] + +## Dependency Rules + +[Describe allowed and forbidden dependencies.] + +## Styling Rules + +[Describe style ownership when the module has UI.] + +## Verification + +[List relevant tests, linters, build commands, and manual checks.] +``` + ## docs/design-docs/index.md Template ```markdown @@ -175,6 +290,43 @@ This document explains the stable structure of the repository. ## Done When ``` +## docs/BACKEND.md Template + +```markdown +# Backend + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +[Describe service, route, repository, validation, worker, and shared package boundaries.] + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +[Describe which services, repositories, validators, and clients must be reused before adding new ones.] + +## File Size Rules + +[Describe when routes, services, jobs, or data-access files must be split.] + +## Verification + +[Describe backend test, lint, typecheck, migration, and smoke-check commands.] +``` + ## docs/references/stack-reference-llms.txt Template ```text @@ -182,6 +334,51 @@ Reference for agents. Include concise commands, constraints, and known pitfalls. ``` +## docs/references/development-rules.md Template + +```markdown +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. +``` + ## docs/references/-llms.txt Template ```text @@ -245,11 +442,54 @@ Pitfalls [Directory layout] +## Styling Ownership + +[Describe where global styles, design tokens, CSS modules, component styles, and feature styles live.] + +## Reuse Rules + +[Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership.] + +## File Size Rules + +[Describe when components, pages, hooks, and stylesheets must be split.] + ## Performance Budget [Lighthouse targets and Core Web Vitals targets] ``` +## docs/INFRASTRUCTURE.md Template + +```markdown +# Infrastructure + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +[Describe environment variables, secret ownership, config files, and deployment settings.] + +## Reuse Rules + +[Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused.] + +## File Size Rules + +[Describe when workflow files, IaC modules, and deployment scripts must be split.] + +## Verification + +[Describe plan, validate, dry-run, CI, and rollback checks.] +``` + ## docs/SECURITY.md Template ```markdown @@ -378,5 +618,5 @@ Pitfalls #!/usr/bin/env bash set -euo pipefail -mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/product-specs docs/references scripts +mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/module-contracts docs/product-specs docs/references scripts ``` diff --git a/targets/claude/harness-init/SKILL.md b/targets/claude/harness-init/SKILL.md index 1863825..a3a4c51 100644 --- a/targets/claude/harness-init/SKILL.md +++ b/targets/claude/harness-init/SKILL.md @@ -14,7 +14,7 @@ It is intended to be packaged for Claude, Claude Code, Codex, OpenCode, and Anti ## Interview Questions -Ask the following 10 questions in order: +Ask the following 11 questions in order: 1. Project name 2. Project description @@ -26,9 +26,10 @@ Ask the following 10 questions in order: 8. Which libraries or tools need `llms.txt` reference files? (for example: react, nextjs, prisma, uv, nixpacks) 9. What are the project's done-when or acceptance criteria? 10. Which existing files, folders, or documents must be referenced? +11. Which major code areas need explicit ownership or module contracts? (for example: frontend, backend, infra, scripts, shared packages) Treat a blank answer for question 8 as the fallback placeholder value `미정`. -Treat blank answers for questions 9 and 10 as the same fallback placeholder value. +Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder value. ## Generation Rules @@ -37,16 +38,23 @@ Treat blank answers for questions 9 and 10 as the same fallback placeholder valu - Write `AGENTS.md` as a document map, not a long manual. - Write `ARCHITECTURE.md` as the top-level structure document for the repository. - Generate `CLAUDE.md` when it is useful for the target project. -- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/product-specs/`, `docs/references/`. +- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/module-contracts/`, `docs/product-specs/`, `docs/references/`. - Use matklad's `ARCHITECTURE.md` style as the reference for the root `ARCHITECTURE.md`. -- Always create the harness core documents: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, and `docs/product-specs/index.md`. +- Always create the harness core 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`, and `docs/references/development-rules.md`. +- Treat code organization as a cross-cutting contract that applies to frontend, backend, infra, scripts, shared packages, generated code, tests, and configuration. +- Keep `AGENTS.md` as a navigation map under 100 lines. +- Add discovery, reuse, file-organization, and subagent handoff rules to `docs/references/development-rules.md` so agents search existing code before adding new modules or large files. +- Add module boundaries, public surfaces, ownership, dependency direction, and large-file split criteria to `ARCHITECTURE.md`. - 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. 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`. - Reflect `doneWhen` in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. - If `projectContext` is not the fallback placeholder value, reflect it in the `AGENTS.md` read order or repository map. +- If `moduleContractAreas` is not the fallback placeholder value, reflect it in `ARCHITECTURE.md`, `docs/generated/code-map.md`, and `docs/module-contracts/README.md`. - Keep installation, run, and usage instructions in `README.md`; keep agent navigation rules in `AGENTS.md`. - Generate `scripts/init.sh` to automate base directory initialization. - Write `README.md` in the user's language or the language explicitly requested for the README. diff --git a/targets/claude/harness-init/references/templates.md b/targets/claude/harness-init/references/templates.md index 46e004f..3994d22 100644 --- a/targets/claude/harness-init/references/templates.md +++ b/targets/claude/harness-init/references/templates.md @@ -14,7 +14,10 @@ Treat the following files as the core harness-engineering set: - `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` - at least one `docs/references/*-llms.txt` file ## Optional Docs @@ -23,10 +26,13 @@ Generate each document only when its stated condition is met: | File | Generate when... | | --- | --- | +| `docs/BACKEND.md` | A backend, API, worker, queue, service layer, or data-access layer is present | | `docs/FRONTEND.md` | A frontend tech stack is present (e.g., React, Vue, Next.js, SvelteKit) | +| `docs/INFRASTRUCTURE.md` | Deployment, hosting, IaC, CI/CD, observability, or runtime configuration is present | | `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 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 | @@ -58,16 +64,30 @@ If the input is blank or resolves to the fallback placeholder value, generate on ## Read Order 1. ARCHITECTURE.md -2. docs/product-specs/index.md -3. docs/exec-plans/active/ -4. docs/design-docs/ -5. docs/references/ +2. docs/references/development-rules.md +3. docs/generated/code-map.md +4. docs/module-contracts/README.md +5. docs/product-specs/index.md +6. docs/exec-plans/active/ +7. docs/design-docs/ +8. docs/references/ ## Repository Map - app/ - docs/ - scripts/ + +## Reference Map + +- Development rules: docs/references/development-rules.md +- Code surface index: docs/generated/code-map.md +- Module contracts: docs/module-contracts/README.md + +## Rules + +- Agents MUST treat this file as a map, not a full manual. +- Agents MUST keep this file under 100 lines. ``` ## README.md Template @@ -97,9 +117,104 @@ This document explains the stable structure of the repository. ## Module Boundaries +## Public Surfaces + +## Dependency Direction + +## File Organization + ## Invariants ``` +## docs/generated/code-map.md Template + +```markdown +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | +``` + +## docs/module-contracts/README.md Template + +```markdown +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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. +``` + +## docs/module-contracts/.md Template + +```markdown +# Module Contract + +## Responsibility + +[Describe what this module owns.] + +## Public Entry Points + +| Name | Kind | Purpose | Source | +| --- | --- | --- | --- | +| `[name]` | `[component, function, class, route, job, script, config]` | `[purpose]` | `[path]` | + +## Internal Reuse + +| Surface | Reuse When | Source | +| --- | --- | --- | +| `[surface]` | `[scenario]` | `[path]` | + +## File Organization + +[Describe the local folder and file naming rules.] + +## Dependency Rules + +[Describe allowed and forbidden dependencies.] + +## Styling Rules + +[Describe style ownership when the module has UI.] + +## Verification + +[List relevant tests, linters, build commands, and manual checks.] +``` + ## docs/design-docs/index.md Template ```markdown @@ -175,6 +290,43 @@ This document explains the stable structure of the repository. ## Done When ``` +## docs/BACKEND.md Template + +```markdown +# Backend + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +[Describe service, route, repository, validation, worker, and shared package boundaries.] + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +[Describe which services, repositories, validators, and clients must be reused before adding new ones.] + +## File Size Rules + +[Describe when routes, services, jobs, or data-access files must be split.] + +## Verification + +[Describe backend test, lint, typecheck, migration, and smoke-check commands.] +``` + ## docs/references/stack-reference-llms.txt Template ```text @@ -182,6 +334,51 @@ Reference for agents. Include concise commands, constraints, and known pitfalls. ``` +## docs/references/development-rules.md Template + +```markdown +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. +``` + ## docs/references/-llms.txt Template ```text @@ -245,11 +442,54 @@ Pitfalls [Directory layout] +## Styling Ownership + +[Describe where global styles, design tokens, CSS modules, component styles, and feature styles live.] + +## Reuse Rules + +[Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership.] + +## File Size Rules + +[Describe when components, pages, hooks, and stylesheets must be split.] + ## Performance Budget [Lighthouse targets and Core Web Vitals targets] ``` +## docs/INFRASTRUCTURE.md Template + +```markdown +# Infrastructure + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +[Describe environment variables, secret ownership, config files, and deployment settings.] + +## Reuse Rules + +[Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused.] + +## File Size Rules + +[Describe when workflow files, IaC modules, and deployment scripts must be split.] + +## Verification + +[Describe plan, validate, dry-run, CI, and rollback checks.] +``` + ## docs/SECURITY.md Template ```markdown @@ -378,5 +618,5 @@ Pitfalls #!/usr/bin/env bash set -euo pipefail -mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/product-specs docs/references scripts +mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/module-contracts docs/product-specs docs/references scripts ``` diff --git a/targets/codex/harness-init/SKILL.md b/targets/codex/harness-init/SKILL.md index 1863825..a3a4c51 100644 --- a/targets/codex/harness-init/SKILL.md +++ b/targets/codex/harness-init/SKILL.md @@ -14,7 +14,7 @@ It is intended to be packaged for Claude, Claude Code, Codex, OpenCode, and Anti ## Interview Questions -Ask the following 10 questions in order: +Ask the following 11 questions in order: 1. Project name 2. Project description @@ -26,9 +26,10 @@ Ask the following 10 questions in order: 8. Which libraries or tools need `llms.txt` reference files? (for example: react, nextjs, prisma, uv, nixpacks) 9. What are the project's done-when or acceptance criteria? 10. Which existing files, folders, or documents must be referenced? +11. Which major code areas need explicit ownership or module contracts? (for example: frontend, backend, infra, scripts, shared packages) Treat a blank answer for question 8 as the fallback placeholder value `미정`. -Treat blank answers for questions 9 and 10 as the same fallback placeholder value. +Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder value. ## Generation Rules @@ -37,16 +38,23 @@ Treat blank answers for questions 9 and 10 as the same fallback placeholder valu - Write `AGENTS.md` as a document map, not a long manual. - Write `ARCHITECTURE.md` as the top-level structure document for the repository. - Generate `CLAUDE.md` when it is useful for the target project. -- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/product-specs/`, `docs/references/`. +- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/module-contracts/`, `docs/product-specs/`, `docs/references/`. - Use matklad's `ARCHITECTURE.md` style as the reference for the root `ARCHITECTURE.md`. -- Always create the harness core documents: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, and `docs/product-specs/index.md`. +- Always create the harness core 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`, and `docs/references/development-rules.md`. +- Treat code organization as a cross-cutting contract that applies to frontend, backend, infra, scripts, shared packages, generated code, tests, and configuration. +- Keep `AGENTS.md` as a navigation map under 100 lines. +- Add discovery, reuse, file-organization, and subagent handoff rules to `docs/references/development-rules.md` so agents search existing code before adding new modules or large files. +- Add module boundaries, public surfaces, ownership, dependency direction, and large-file split criteria to `ARCHITECTURE.md`. - 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. 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`. - Reflect `doneWhen` in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. - If `projectContext` is not the fallback placeholder value, reflect it in the `AGENTS.md` read order or repository map. +- If `moduleContractAreas` is not the fallback placeholder value, reflect it in `ARCHITECTURE.md`, `docs/generated/code-map.md`, and `docs/module-contracts/README.md`. - Keep installation, run, and usage instructions in `README.md`; keep agent navigation rules in `AGENTS.md`. - Generate `scripts/init.sh` to automate base directory initialization. - Write `README.md` in the user's language or the language explicitly requested for the README. diff --git a/targets/codex/harness-init/references/templates.md b/targets/codex/harness-init/references/templates.md index 46e004f..3994d22 100644 --- a/targets/codex/harness-init/references/templates.md +++ b/targets/codex/harness-init/references/templates.md @@ -14,7 +14,10 @@ Treat the following files as the core harness-engineering set: - `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` - at least one `docs/references/*-llms.txt` file ## Optional Docs @@ -23,10 +26,13 @@ Generate each document only when its stated condition is met: | File | Generate when... | | --- | --- | +| `docs/BACKEND.md` | A backend, API, worker, queue, service layer, or data-access layer is present | | `docs/FRONTEND.md` | A frontend tech stack is present (e.g., React, Vue, Next.js, SvelteKit) | +| `docs/INFRASTRUCTURE.md` | Deployment, hosting, IaC, CI/CD, observability, or runtime configuration is present | | `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 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 | @@ -58,16 +64,30 @@ If the input is blank or resolves to the fallback placeholder value, generate on ## Read Order 1. ARCHITECTURE.md -2. docs/product-specs/index.md -3. docs/exec-plans/active/ -4. docs/design-docs/ -5. docs/references/ +2. docs/references/development-rules.md +3. docs/generated/code-map.md +4. docs/module-contracts/README.md +5. docs/product-specs/index.md +6. docs/exec-plans/active/ +7. docs/design-docs/ +8. docs/references/ ## Repository Map - app/ - docs/ - scripts/ + +## Reference Map + +- Development rules: docs/references/development-rules.md +- Code surface index: docs/generated/code-map.md +- Module contracts: docs/module-contracts/README.md + +## Rules + +- Agents MUST treat this file as a map, not a full manual. +- Agents MUST keep this file under 100 lines. ``` ## README.md Template @@ -97,9 +117,104 @@ This document explains the stable structure of the repository. ## Module Boundaries +## Public Surfaces + +## Dependency Direction + +## File Organization + ## Invariants ``` +## docs/generated/code-map.md Template + +```markdown +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | +``` + +## docs/module-contracts/README.md Template + +```markdown +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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. +``` + +## docs/module-contracts/.md Template + +```markdown +# Module Contract + +## Responsibility + +[Describe what this module owns.] + +## Public Entry Points + +| Name | Kind | Purpose | Source | +| --- | --- | --- | --- | +| `[name]` | `[component, function, class, route, job, script, config]` | `[purpose]` | `[path]` | + +## Internal Reuse + +| Surface | Reuse When | Source | +| --- | --- | --- | +| `[surface]` | `[scenario]` | `[path]` | + +## File Organization + +[Describe the local folder and file naming rules.] + +## Dependency Rules + +[Describe allowed and forbidden dependencies.] + +## Styling Rules + +[Describe style ownership when the module has UI.] + +## Verification + +[List relevant tests, linters, build commands, and manual checks.] +``` + ## docs/design-docs/index.md Template ```markdown @@ -175,6 +290,43 @@ This document explains the stable structure of the repository. ## Done When ``` +## docs/BACKEND.md Template + +```markdown +# Backend + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +[Describe service, route, repository, validation, worker, and shared package boundaries.] + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +[Describe which services, repositories, validators, and clients must be reused before adding new ones.] + +## File Size Rules + +[Describe when routes, services, jobs, or data-access files must be split.] + +## Verification + +[Describe backend test, lint, typecheck, migration, and smoke-check commands.] +``` + ## docs/references/stack-reference-llms.txt Template ```text @@ -182,6 +334,51 @@ Reference for agents. Include concise commands, constraints, and known pitfalls. ``` +## docs/references/development-rules.md Template + +```markdown +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. +``` + ## docs/references/-llms.txt Template ```text @@ -245,11 +442,54 @@ Pitfalls [Directory layout] +## Styling Ownership + +[Describe where global styles, design tokens, CSS modules, component styles, and feature styles live.] + +## Reuse Rules + +[Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership.] + +## File Size Rules + +[Describe when components, pages, hooks, and stylesheets must be split.] + ## Performance Budget [Lighthouse targets and Core Web Vitals targets] ``` +## docs/INFRASTRUCTURE.md Template + +```markdown +# Infrastructure + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +[Describe environment variables, secret ownership, config files, and deployment settings.] + +## Reuse Rules + +[Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused.] + +## File Size Rules + +[Describe when workflow files, IaC modules, and deployment scripts must be split.] + +## Verification + +[Describe plan, validate, dry-run, CI, and rollback checks.] +``` + ## docs/SECURITY.md Template ```markdown @@ -378,5 +618,5 @@ Pitfalls #!/usr/bin/env bash set -euo pipefail -mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/product-specs docs/references scripts +mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/module-contracts docs/product-specs docs/references scripts ``` diff --git a/targets/opencode/harness-init/SKILL.md b/targets/opencode/harness-init/SKILL.md index 1863825..a3a4c51 100644 --- a/targets/opencode/harness-init/SKILL.md +++ b/targets/opencode/harness-init/SKILL.md @@ -14,7 +14,7 @@ It is intended to be packaged for Claude, Claude Code, Codex, OpenCode, and Anti ## Interview Questions -Ask the following 10 questions in order: +Ask the following 11 questions in order: 1. Project name 2. Project description @@ -26,9 +26,10 @@ Ask the following 10 questions in order: 8. Which libraries or tools need `llms.txt` reference files? (for example: react, nextjs, prisma, uv, nixpacks) 9. What are the project's done-when or acceptance criteria? 10. Which existing files, folders, or documents must be referenced? +11. Which major code areas need explicit ownership or module contracts? (for example: frontend, backend, infra, scripts, shared packages) Treat a blank answer for question 8 as the fallback placeholder value `미정`. -Treat blank answers for questions 9 and 10 as the same fallback placeholder value. +Treat blank answers for questions 9, 10, and 11 as the same fallback placeholder value. ## Generation Rules @@ -37,16 +38,23 @@ Treat blank answers for questions 9 and 10 as the same fallback placeholder valu - Write `AGENTS.md` as a document map, not a long manual. - Write `ARCHITECTURE.md` as the top-level structure document for the repository. - Generate `CLAUDE.md` when it is useful for the target project. -- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/product-specs/`, `docs/references/`. +- Always create the base directory structure: `docs/design-docs/`, `docs/exec-plans/active/`, `docs/exec-plans/completed/`, `docs/generated/`, `docs/module-contracts/`, `docs/product-specs/`, `docs/references/`. - Use matklad's `ARCHITECTURE.md` style as the reference for the root `ARCHITECTURE.md`. -- Always create the harness core documents: `docs/design-docs/index.md`, `docs/design-docs/core-beliefs.md`, `docs/exec-plans/tech-debt-tracker.md`, and `docs/product-specs/index.md`. +- Always create the harness core 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`, and `docs/references/development-rules.md`. +- Treat code organization as a cross-cutting contract that applies to frontend, backend, infra, scripts, shared packages, generated code, tests, and configuration. +- Keep `AGENTS.md` as a navigation map under 100 lines. +- Add discovery, reuse, file-organization, and subagent handoff rules to `docs/references/development-rules.md` so agents search existing code before adding new modules or large files. +- Add module boundaries, public surfaces, ownership, dependency direction, and large-file split criteria to `ARCHITECTURE.md`. - 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. 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`. - Reflect `doneWhen` in `AGENTS.md` and in at least one document under `docs/product-specs/` or `docs/exec-plans/active/`. - If `projectContext` is not the fallback placeholder value, reflect it in the `AGENTS.md` read order or repository map. +- If `moduleContractAreas` is not the fallback placeholder value, reflect it in `ARCHITECTURE.md`, `docs/generated/code-map.md`, and `docs/module-contracts/README.md`. - Keep installation, run, and usage instructions in `README.md`; keep agent navigation rules in `AGENTS.md`. - Generate `scripts/init.sh` to automate base directory initialization. - Write `README.md` in the user's language or the language explicitly requested for the README. diff --git a/targets/opencode/harness-init/references/templates.md b/targets/opencode/harness-init/references/templates.md index 46e004f..3994d22 100644 --- a/targets/opencode/harness-init/references/templates.md +++ b/targets/opencode/harness-init/references/templates.md @@ -14,7 +14,10 @@ Treat the following files as the core harness-engineering set: - `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` - at least one `docs/references/*-llms.txt` file ## Optional Docs @@ -23,10 +26,13 @@ Generate each document only when its stated condition is met: | File | Generate when... | | --- | --- | +| `docs/BACKEND.md` | A backend, API, worker, queue, service layer, or data-access layer is present | | `docs/FRONTEND.md` | A frontend tech stack is present (e.g., React, Vue, Next.js, SvelteKit) | +| `docs/INFRASTRUCTURE.md` | Deployment, hosting, IaC, CI/CD, observability, or runtime configuration is present | | `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 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 | @@ -58,16 +64,30 @@ If the input is blank or resolves to the fallback placeholder value, generate on ## Read Order 1. ARCHITECTURE.md -2. docs/product-specs/index.md -3. docs/exec-plans/active/ -4. docs/design-docs/ -5. docs/references/ +2. docs/references/development-rules.md +3. docs/generated/code-map.md +4. docs/module-contracts/README.md +5. docs/product-specs/index.md +6. docs/exec-plans/active/ +7. docs/design-docs/ +8. docs/references/ ## Repository Map - app/ - docs/ - scripts/ + +## Reference Map + +- Development rules: docs/references/development-rules.md +- Code surface index: docs/generated/code-map.md +- Module contracts: docs/module-contracts/README.md + +## Rules + +- Agents MUST treat this file as a map, not a full manual. +- Agents MUST keep this file under 100 lines. ``` ## README.md Template @@ -97,9 +117,104 @@ This document explains the stable structure of the repository. ## Module Boundaries +## Public Surfaces + +## Dependency Direction + +## File Organization + ## Invariants ``` +## docs/generated/code-map.md Template + +```markdown +# Code Map + +This generated index helps agents find and reuse existing code 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 | +| --- | --- | --- | --- | --- | --- | +| Frontend | `app/` | Routes, pages, UI components | User-facing screens and interactions | Existing routes, feature components, shared UI primitives | `app/` | +| Backend | `server/` | API handlers, services, workers | Server-side behavior and data workflows | Existing services, repositories, validators, jobs | `server/` | +| Infra | `infra/` | IaC, deployment config, CI/CD | Runtime platform and operational wiring | Existing modules, environment conventions, workflow jobs | `infra/` | +| Scripts | `scripts/` | Shell or task scripts | Local and CI automation | Existing commands and shared script helpers | `scripts/` | +| Shared | `packages/` | Public package exports | Cross-runtime reusable logic | Existing package exports and module contracts | `packages/` | +| Styles | `styles/` | Tokens, resets, globals | App-wide styling foundations | Existing tokens, CSS modules, component-local styles | `styles/` | +| Tests | `tests/` | Fixtures, prompts, test helpers, reports | Verification and regression coverage | Existing fixtures, helpers, snapshots, and test conventions | `tests/` | +| Generated | `docs/generated/` | Generated indexes and derived facts | Machine- or tool-generated project references | Existing generated docs before adding derived surfaces | `docs/generated/` | + +## Large Files + +| File | Lines | Owner | Split Plan | +| --- | --- | --- | --- | +| `[path]` | `[count]` | `[owner]` | `[split or keep rationale]` | +``` + +## docs/module-contracts/README.md Template + +```markdown +# Module Contracts + +Module contracts describe owned code areas so agents can reuse existing surfaces and avoid catch-all files. + +## Contract Index + +| Module | Contract | Owner | Scope | +| --- | --- | --- | --- | +| `[module]` | `docs/module-contracts/.md` | `[owner]` | `[frontend, backend, infra, scripts, shared, tests, generated]` | + +## 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. +``` + +## docs/module-contracts/.md Template + +```markdown +# Module Contract + +## Responsibility + +[Describe what this module owns.] + +## Public Entry Points + +| Name | Kind | Purpose | Source | +| --- | --- | --- | --- | +| `[name]` | `[component, function, class, route, job, script, config]` | `[purpose]` | `[path]` | + +## Internal Reuse + +| Surface | Reuse When | Source | +| --- | --- | --- | +| `[surface]` | `[scenario]` | `[path]` | + +## File Organization + +[Describe the local folder and file naming rules.] + +## Dependency Rules + +[Describe allowed and forbidden dependencies.] + +## Styling Rules + +[Describe style ownership when the module has UI.] + +## Verification + +[List relevant tests, linters, build commands, and manual checks.] +``` + ## docs/design-docs/index.md Template ```markdown @@ -175,6 +290,43 @@ This document explains the stable structure of the repository. ## Done When ``` +## docs/BACKEND.md Template + +```markdown +# Backend + +## Runtime + +| Concern | Choice | +| --- | --- | +| Language | ... | +| Framework | ... | +| Data Access | ... | +| Background Jobs | ... | + +## Module Organization + +[Describe service, route, repository, validation, worker, and shared package boundaries.] + +## Public Entry Points + +| Surface | Purpose | Owner | Source | +| --- | --- | --- | --- | +| ... | ... | ... | ... | + +## Reuse Rules + +[Describe which services, repositories, validators, and clients must be reused before adding new ones.] + +## File Size Rules + +[Describe when routes, services, jobs, or data-access files must be split.] + +## Verification + +[Describe backend test, lint, typecheck, migration, and smoke-check commands.] +``` + ## docs/references/stack-reference-llms.txt Template ```text @@ -182,6 +334,51 @@ Reference for agents. Include concise commands, constraints, and known pitfalls. ``` +## docs/references/development-rules.md Template + +```markdown +# Development Rules + +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. +- Agents MUST read `docs/generated/code-map.md` before adding long-lived files or modules. +- Agents MUST read the relevant `docs/module-contracts/` file before editing an owned module. +- Agents MUST prefer reusing or extending an owned module over creating a parallel implementation. + +## File Organization + +- Agents MUST keep code organized by feature, domain, runtime boundary, or infrastructure responsibility. +- Agents MUST NOT create or grow catch-all files when a smaller owned module can hold the behavior. +- Agents SHOULD split files above 400 lines before adding more behavior. +- Agents MUST split files above 800 lines or document why they must stay consolidated. +- Agents MUST name files by responsibility so the file name explains the feature, module, or runtime surface it owns. +- Agents MUST place new code near the feature, service, component, script, or infrastructure module that owns it unless the code is genuinely shared. + +## Surface Updates + +- Agents MUST update `docs/generated/code-map.md` when public entry points, reusable surfaces, or file layout changes. +- Agents MUST update the relevant `docs/module-contracts/` file when ownership, dependency rules, verification commands, or module boundaries change. +- Agents MUST add a new module contract when creating a long-lived feature, package, service, infrastructure area, or script suite with explicit ownership. + +## Subagent Handoff + +- Delegation prompts MUST include the goal, write scope, relevant read order, done-when criteria, and forbidden changes. +- Subagents MUST inspect the relevant code map and module contract before implementation. +- Subagents MUST keep changes inside the assigned write scope unless they report a blocker first. +- Subagents MUST report existing surfaces reused, new surfaces added, files changed, tests run, and unresolved risks. +``` + ## docs/references/-llms.txt Template ```text @@ -245,11 +442,54 @@ Pitfalls [Directory layout] +## Styling Ownership + +[Describe where global styles, design tokens, CSS modules, component styles, and feature styles live.] + +## Reuse Rules + +[Describe shared UI primitives, feature components, hooks, state modules, and route-level ownership.] + +## File Size Rules + +[Describe when components, pages, hooks, and stylesheets must be split.] + ## Performance Budget [Lighthouse targets and Core Web Vitals targets] ``` +## docs/INFRASTRUCTURE.md Template + +```markdown +# Infrastructure + +## Runtime Surfaces + +| Surface | Responsibility | Owner | Source | +| --- | --- | --- | --- | +| Hosting | ... | ... | ... | +| CI/CD | ... | ... | ... | +| IaC | ... | ... | ... | +| Observability | ... | ... | ... | + +## Configuration Ownership + +[Describe environment variables, secret ownership, config files, and deployment settings.] + +## Reuse Rules + +[Describe existing Terraform modules, workflow jobs, deployment scripts, monitoring conventions, and runtime helpers that must be reused.] + +## File Size Rules + +[Describe when workflow files, IaC modules, and deployment scripts must be split.] + +## Verification + +[Describe plan, validate, dry-run, CI, and rollback checks.] +``` + ## docs/SECURITY.md Template ```markdown @@ -378,5 +618,5 @@ Pitfalls #!/usr/bin/env bash set -euo pipefail -mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/product-specs docs/references scripts +mkdir -p docs/design-docs docs/exec-plans/active docs/exec-plans/completed docs/generated docs/module-contracts docs/product-specs docs/references scripts ```