67 lines
2.0 KiB
Markdown
67 lines
2.0 KiB
Markdown
# Rule `agent-docs/` Template
|
|
|
|
Use this structure for Markdown files inside `agent-docs/` when the document's main job is to govern behavior: rules, policy, constraints, decision criteria, or workflow guidance.
|
|
|
|
## Minimum Required Shape
|
|
|
|
```md
|
|
# <Document Title>
|
|
|
|
<Opening statement: what this doc governs, when it applies, and that it must be followed in scope.>
|
|
|
|
## Applies To
|
|
|
|
- <specific task or document types>
|
|
|
|
## Does Not Apply To
|
|
|
|
- <out-of-scope task or document types>
|
|
|
|
## Authority
|
|
|
|
- <source of truth: owning doc, repository path, command, or code area>
|
|
|
|
## <Rule Section>
|
|
|
|
- <instructions>
|
|
|
|
## Edge Cases
|
|
|
|
- <exceptions, ambiguous cases, or branch conditions>
|
|
|
|
## Failure Modes
|
|
|
|
- <what usually goes wrong and how to recover>
|
|
|
|
## Checklist
|
|
|
|
- <validation questions>
|
|
```
|
|
|
|
## Required Sections
|
|
|
|
- `# <Document Title>`
|
|
- opening statement
|
|
- `## Applies To`
|
|
- `## Authority`
|
|
- at least one topic-specific rule section
|
|
- `## Checklist`
|
|
|
|
## Conditionally Required Sections
|
|
|
|
- `## Does Not Apply To` when scope boundaries are easy to misread or likely to overlap with sibling docs
|
|
- `## Edge Cases` when branch conditions or exceptions would otherwise be inferred
|
|
- `## Failure Modes` when maintainers need recovery guidance or common-mistake handling
|
|
|
|
## Notes
|
|
|
|
- Make the scope explicit.
|
|
- Keep the document responsible for one topic.
|
|
- Use semantic filenames and headings.
|
|
- Write for maintainers. State actions, constraints, and decision criteria directly.
|
|
- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.
|
|
- State the user or maintainer decision directly: what to do, what to avoid, and how to choose.
|
|
- Treat `Authority` as required. If no authority can be named, the rule is probably too vague or not ready to be canonicalized.
|
|
- Add `Edge Cases` and `Failure Modes` when the workflow is easy to misapply or the scope boundary is easy to misunderstand.
|
|
- Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.
|