Skip to content

Commit 15f2a9c

Browse files
committed
docs: restore two rules dropped by the AGENTS.md split
Review caught two repo-specific rules that did not survive the move. Both are prose without any backticked identifier, so the identifier-diff used to verify the split could not see them. - "Test through public interfaces; do not add unrelated production exports solely to enable tests" returns next to the behavioral-tests rule in docs/agents/testing.md, with the reason it exists. - The guidance-ownership rule (decide whether new guidance/schema/metadata belongs to the command surface, CLI grammar, CLI help, MCP projection, or daemon runtime) returns to the always-loaded Docs & skills section, since it governs all command-surface work and not just the flag case. Also point the ADR routing row at docs/adr/README.md, which is already the "read when you touch…" index, rather than at the bare directory.
1 parent c63aaae commit 15f2a9c

2 files changed

Lines changed: 10 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ situational lives one hop away — load it when the task calls for it.
1010
| When the task involves | Read |
1111
| --- | --- |
1212
| Domain vocabulary, architecture language, capture-reliability contract | `CONTEXT.md` |
13-
| Accepted architecture decisions | `docs/adr/` |
13+
| Accepted architecture decisions | `docs/adr/README.md` (a "read when you touch…" index) |
1414
| Which gates to run, test speed rules, shared fixtures | `docs/agents/testing.md` |
1515
| Adding or changing a CLI flag | `docs/agents/cli-flags.md` |
1616
| Opening a PR, or reviewing one | `docs/agents/pull-requests.md` |
@@ -219,6 +219,10 @@ connect errors, retry policy, or command typing, start in
219219

220220
## Docs & skills
221221

222+
- Before adding guidance, examples, schemas, or command metadata anywhere, decide which layer owns
223+
it: the command surface, CLI grammar, CLI help, MCP projection, or daemon runtime. Picking the
224+
layer after writing is how the same contract ends up duplicated across two of them.
225+
`docs/agents/cli-flags.md` walks the layers for the flag case.
222226
- Decide docs impact with the change, not after. For behavior/CLI-surface changes: update
223227
help/metadata, README or `website/docs/**` when user-facing, and a SkillGym case in
224228
`test/skillgym/suites/agent-device-smoke-suite.ts` when command-planning guidance changes.

‎docs/agents/testing.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,11 @@ it through the barrel.
4242

4343
Keep tests behavioral. Do not assert shapes or cases TypeScript already proves.
4444

45+
Test through public interfaces where practical, and do not add unrelated production exports solely
46+
to make a test easier — widening the public surface for a test is a product change, and the exports
47+
outlive the test that motivated them. If a seam is genuinely missing, add it as a real one rather
48+
than as a test affordance (the workflow separately forbids test-only `typeof` DI params).
49+
4550
## Affected-check selector (`pnpm check:affected`)
4651

4752
`pnpm check:affected --base <ref>` derives which local checks a diff needs, so

0 commit comments

Comments
 (0)