Appearance
date: 2026-06-11 tags: [harness, docs, dry, skills, organisation] status: active graduated_to:
When ≥2 skills need the same contract, extract it to one referenced doc
Pattern — the moment a rule/contract/recipe is needed in two or more skills or docs, don't inline it in each (they drift). Lift it into one on-demand reference doc under docs/agents/, and have each consumer point at it with only its own deltas added. The DRY principle, applied to harness prose.
Precedents — agent-brief.md, qa-ui-contract.md, ui-patterns.md, then this session orchestration.md and deterministic-merge.md. Each is referenced by several skills/rules rather than copied into them.
The mechanics that make it work
- The doc is on-demand (loaded only when a consumer invokes it), with a single always-on index line in
CLAUDE.mdso it's discoverable without bloating every session. - Consumers carry a one-line pointer (
follows docs/agents/<x>.md) + their own deltas — never a copy. (Seebuild-sprintpointing atorchestration.md,ideate§3 pointing atdeterministic-merge.md.) - Mirror the harness's existing "describe what it is, never who calls it" rule: the shared doc states the contract; the caller list lives with the callers, so a rename doesn't desync.
Why — two copies of a contract is two things to update and one to forget; one referenced doc is the single source of truth. Same reasoning as "config co-locates with the consumer that owns it" (skills.md) and "no premature abstraction — extract on the second use case, not the first" (code-quality.md).
Promotion note — recurring often enough that it's a candidate to graduate into a .claude/rules/ line (always-on) on the next find-learnings --refresh; left as a learning for now to avoid adding always-on context before it's earned.