Working with the agent
How the agent is configured and steered. Sources: REF-CC-BEST-PRACTICES, REF-CC-MEMORY, REF-CC-SKILLS, REF-CC-HOOKS, REF-CC-SUBAGENTS, REF-ANTHROPIC-CONTEXT; decision ADR-0021. This project's files: agent configuration.
Configuration
| Need | Mechanism |
|---|---|
| rules for any agent | AGENTS.md, short; every line prevents a mistake |
| what only one tool uses | CLAUDE.md importing AGENTS.md, then its own section |
| pitfalls of one area | .claude/rules/*.md with paths: |
| multi-step procedures | skills (/story, /run, /spike, /audit, /review, /retro…) |
| second opinions | read-only expert agents in a fresh context, told to refute, run in the background |
| what must never happen | a PreToolUse hook that denies with a reason, not an instruction |
| state after a compaction | a SessionStart hook printing facts derived from the files |
| what the agent is doing, live | a status line: backlog place, step, activity, time, tokens, the call running |
| how long things take | hooks timing every call; a metrics report per epic |
| sources without reading them twice | a local library behind an MCP server |
| preferences across projects | the agent's memory, one fact per file |
Steering
- Ask for evidence: the command, its output, the source read.
- Give a check the agent can run; without one, "looks done" is the only signal.
- Business questions are answered by the Product Owner and written in the domain; the agent stops and asks rather than choose.
- A repeated mistake gets a check (lint rule, test, hook) and a line in lessons, not a sentence.
- Ask for pushback: the agent says when a request is a bad idea, with sources.
- Long runs: start one, leave it; the status line shows whether it works or waits.
- Parallel sessions: a second chat works in its own worktree from
develop, writes every decision in the repository and messages the run (agent configuration).
The Product Owner's role
The agent designs, implements, tests and documents. The Product Owner sets priorities, answers business questions, sets stories ready, runs the guided tests, merges features and releases. They read the result, not the code: checks, demos and audits stand for line-by-line review. They never touch the repository; the agent writes their decisions in neutral words.
Lessons from the Product Owner
The Product Owner's critiques of E01, written as habits: what the agent does in each situation.
| When the agent is about to… | Instead |
|---|---|
| ask a refinement question | search the past features and the domain first; never ask again what is settled (point numbering, renumbering) |
| ask the Product Owner to choose | use the questionnaire; each option with a short example in numbers; never a drawing made of characters |
| propose a shape or a behavior | read first how the reference tools do it, and raise the open questions it touches at the refinement |
| refine a feature | ask only what the feature needs; write the Product Owner's other ideas in the domain for later |
| name a term in a question | say it in plain words the first time ("the rounding of the corners") |
| ask the Product Owner to test | name the branch checked out, check it is up to date, give the direct link to the step |
| open a feature pull request | clean every status and branch first, say all is clean, wait for a yes; push nothing else meanwhile |
| design a page clicked over and over | put the controls first and large; check with the longest and shortest content |
| write a test card | show why a choice exists, not only what it does |
| upgrade a dependency | read its release notes first; adapt the configuration to new features and breaking changes |
| report progress | show the step, not the diffs; during a run, only the commits and one summary |
| wait for something | read the statuses; stop at the first failure; never wait for a CI on a work branch |
| record what the Product Owner said | write the decision and its reason in neutral English, never quote |
| add code | only for stories the Product Owner set ready |