Guides
Guides steer the agent before it acts. They are the feedforward half of the harness, plain markdown under each agent's guides/ directory. Sensors and evals catch a mistake after the fact and cost a retry; a guide prevents it. When an artifact keeps failing the same eval check, fix the guide before you tighten the eval.
Kinds of guide
| Guide | Role |
|---|---|
pipeline.md |
an agent's operating rules: stages, retry policy, approval markers, token accounting |
writing-style.md |
voice, banned words, punctuation, tables versus bullets, mermaid over ASCII (product-manager, system-architect) |
*-guidelines.md |
artifact rules, such as prd-guidelines.md and prp-guidelines.md |
templates/*.md |
the skeleton the artifact fills |
examples/good-*.md |
a finished artifact written to the standard |
design-method.md |
the method and canon of the system-architect agent |
coding-style.md, commit-style.md |
code and commit rules for the staff-software-engineer agent |
conventions-override.md |
how per-repo conventions layer over SSE defaults |
sdd-loop.md |
the spec-driven loop and its predicate |
Templates and examples
A template is the strongest feedforward control: the agent fills a skeleton instead of inventing a shape. A good example adds the texture of finished work. harness-kit ships good-prd-example.md, good-prp-example.md, and good-system-design-example.md.
Internal guides, sensors, and evals are written in terse caveman style to save input tokens. Templates and examples stay in natural English because they model artifacts that stakeholders read.
Conventions per repo
The staff-software-engineer agent has defaults per discipline. A consumer repo overrides them with files here:
{your-repo}/.claude/conventions/{backend,web,mobile,devops}.md
When a file exists, the agent reads it on top of its defaults and the project wins. This is the per-discipline paving of the golden path, and it pins the shape the code must fit.
Voice and banned words
writing-style.md bans the common AI tells such as delve, leverage, utilize, and robust, forbids em dashes, requires mermaid over ASCII, and asks for real numbers, names, and quotes. The evals enforce the same rules in code: - absent: regexes in each rubric fail a check on a banned word, an em dash, or an ASCII box diagram without asking the judge. See Evals.
Writing a good guide
Be concrete: "lead with the decision, then the reason" teaches more than "write clearly". Pair each rule with a two-line good and bad example. Give the agent a template to fill rather than ten prose rules. When a sensor's feedback points to a guide, phrase the guide so the agent can act on it in the next turn.
See also Harness Engineering, Sensors, Evals.
This page mirrors Guides in the wiki. Edit it there.