Each file states the intent of one major system: the goals it must meet,
where users reach it, and the rules users rely on. Teammates read it to learn
why the system works the way it does. Agents read it before they change the
system. The create-design-docs skill writes these files, and the
maintain-design-docs skill checks the product against them.
Each file has an H1 title and one paragraph that says what the user gets. Then it has these H2 sections, in this order:
Intent: the goals that the system must meet, and why. Each goal decides between real options, such as "runs work with no person present".Entry points: each place where a user reaches the system, by its visible name.Rules: limits that users rely on, such as who can act, and what the system is not.Gaps: only when the product does not meet a goal or a rule yet. Say how it falls short, and which goal or rule it breaks.
These files state intent. The code shows what the product does, not what it should do. Do not change a goal or a rule only to match the code. Name only user actions, visible names, required access, and outcomes that a user can see. Leave out source paths, symbols, schemas, history, and rollout notes.
Do not list behaviors. When the repo has a verification skill, its map owns
each behavior as a claim with a proof. Name a behavior only by its claim ID,
such as automations#run-now, and do not restate it.
- MCP tools: the Sentry tools an agent can list and call, and how it finds the right one.
- MCP tool responses: what a tool result gives an agent to answer a Sentry question.
- MCP Apps views: interactive views that MCP Apps hosts render inline for a tool result.
- MCP access: who can use Sentry MCP, over which transport, and what a session can reach.
- Sentry CLI: the
sentrycommand for people and agents in a terminal. - Sentry Local: the app telemetry
sentry localcaptures on a developer's machine, with no account.