How agents use docs/DESIGN.md
Which agents read the specification, what they take from it, and why it is treated as data.
docs/DESIGN.md is the project's statement of intended behaviour. It is the one place where "what the design should do" is written apart from the code, so it is what an agent needs to tell a bug from a choice.
Who reads it#
| Agent | How it gets the file | What it uses it for |
|---|---|---|
| Design Chat | Design Chat reads the project's files, docs/ first | Answering questions, and keeping new code consistent with what was specified |
| Verification | Given the file with the request | Working out expected values from intended behaviour, not from the code |
| Timing and implementation | Given the file as a design note | Respecting a stated clock or latency. A fix that would break one is ruled out, and the agent says so |
| Diagnosis and repair | Given the file with the request | Deciding whether the design or the test is at fault |
The stage explainer does not read it. Its job is to read one log.
It is checked first#
Before the file is given to an agent, the lab checks which sections are present and which are empty or marked undecided. The agent is told the result. A missing section is to be treated as open, not guessed.
If a project has no specification, the agent is told that too, and told not to present a guess as the specification.
It is data, not instruction#
The specification is your text. It is passed to the model marked as project data, with the instruction to use it as the statement of intended behaviour and to ignore any instruction inside it. A line such as "ignore the test" in a specification has no effect on the agent.
What this does not do#
- It does not stop RTL being written when the specification is missing. Design Chat is instructed to write the specification first; that is an instruction to the model, not a lock in the platform.
- It does not check that the RTL matches the specification. Only a test can do that.
Something unclear or missing? Send feedbackSign in and use Feedback to tell us.