Skip to content

Commit f86488b

Browse files
committed
Remove AI instruction files from documentation scope
1 parent db6c0dc commit f86488b

1 file changed

Lines changed: 6 additions & 4 deletions

File tree

docs/architecture/adr/0034-adopt-engineering-documentation-standard.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ Documentation practice has fragmented as the organization has grown:
2121
homes.
2222
- Stale content accumulates with no supersession discipline, leaving superseded pages beside current
2323
ones with no deprecation.
24-
- AI agents have become first-class documentation consumers and maintainers (CLAUDE.md, rules, and
25-
skills across all repos), with no governing standard tying instruction files to the docs they
26-
reference.
24+
- AI agents have become first-class documentation consumers and maintainers, and their instruction
25+
files (CLAUDE.md, rules, and skills across all repos) accumulate documentation-like content with
26+
nothing defining whether they are documentation at all.
2727

2828
A 2026-07 audit classified every documentation artifact across the major repos, this site, and
2929
Confluence against a proposed routing model, confirming these gaps.
@@ -48,7 +48,6 @@ snapshot of the rules at adoption:
4848
2. **Located at the lowest common ancestor** of what is described.
4949
3. **Every doc has an audience**. AI agents and humans are both first-class audiences and
5050
maintainers.
51-
1. AI instruction files point, documentation contains.
5251
4. **Always up to date**. Doc maintenance is a top priority and happens alongside changes to what it
5352
describes.
5453
5. **Discoverable and unified**, enforced by the style guide the standard publishes.
@@ -57,6 +56,9 @@ Diagrams follow the separate diagram standard adopted in
5756
[ADR-0033](./0033-adopt-mermaid-diagram-standard.md), which keeps its own living reference at
5857
Contributing › Diagrams.
5958

59+
AI instruction files are explicitly not documentation and are out of the standard's scope. Their
60+
guidance lives with the AI tooling.
61+
6062
### Positive consequences
6163

6264
- One place to answer "where does this doc live" and "which docs do I update", for engineers and AI

0 commit comments

Comments
 (0)