docs: restructure server and web documentation into ADR files and a

routing table
2026-07-17 22:07:55 +08:00
parent f8494a44ca
commit 519aa35f1f
23 changed files with 710 additions and 654 deletions
@@ -0,0 +1,65 @@
+# Documentation Writing Guide
+
+## Goals
+
+Repository documentation must be accurate, concise, and useful to both people and coding agents.
+
+## Document Roles
+
+| Document type | Content |
+|---------------|---------|
+| README | Project entry point and runnable paths |
+| Architecture | Current structure, responsibilities, and enforced boundaries |
+| Development | Commands and operational procedures |
+| Roadmap | Available, planned, and future capabilities |
+| Architecture Decision Record (ADR) | One technical decision, its context, and its consequences |
+| `AGENTS.md` | Durable agent workflow, conventions, verification, and constraints |
+
+Keep each fact in its canonical document. Link to that document from other locations.
+
+## Current-State Writing
+
+- Use English, active voice, and present tense.
+- Name the component that performs each action.
+- Put one fact or instruction in each sentence or list item.
+- Prefer short sections, lists, and tables.
+- State the supported path before optional details.
+- Use `must` for requirements, `can` for optional behavior, and present tense for existing behavior.
+- Use current commands, symbols, routes, and examples.
+
+## Constraints and Anti-Patterns
+
+Keep a negative rule **only when** it prevents a current and plausible mistake with a meaningful cost. This includes:
+
+- Tooling traps that reduce reproducibility or pollute context
+- Architecture boundaries enforced by tests
+- Security, authorization, and destructive-action limits
+- Commit and dependency-change authorization
+
+Place the rule near the affected workflow and provide the supported path. Keep one canonical copy when the same audience reads multiple documents.
+
+Remove or move a negative statement when it describes a hypothetical design, repeats a positive contract, or explains an obsolete implementation. Preserve material history in the relevant ADR instead.
+
+## Decision Records
+
+- Record one logical decision per ADR.
+- Put the status before the body.
+- Describe requirements and forces in Context.
+- State the selected design in Decision.
+- Record current trade-offs in Consequences.
+- Link superseded records to their replacement.
+- Use past tense for historical implementation details.
+
+## Review Checklist
+
+1. Confirm the document type and audience.
+2. Verify facts against code and configuration.
+3. Remove duplicated current-state information.
+4. Check every negative statement for a current action or decision.
+5. Verify commands, examples, and local links.
+6. Run `git diff --check`.
+
+## References
+
+- [OpenAI Codex best practices](https://learn.chatgpt.com/guides/best-practices)
+- [Architectural Decision Records](https://adr.github.io/)