Required reading at startup
Before starting any judgment or action, first read .codestable/attention.md; if missing, treat the skeleton as incomplete and prompt to fill it in first or run cs-onboard, and do not fall back to an external AI entry file.
Code solves the problem; documentation lets others use it to solve the problem. The spec records "what was done and why it was done this way", but downstream developers and end users do not need to—and should not—read the spec; they need publishable guides oriented to their own roles. guidedoc is exactly about starting from the spec and the code to write guides that readers can truly use.
Two tracks
| Track | Target readers | Typical content | Output path |
|---|---|---|---|
dev-guide |
Contributors, integrators, downstream developers | Local setup, architecture explanation, API description, extension methods | docs/dev/{slug}.md |
user-guide |
End users | Feature overview, operating steps, concept explanations, FAQs | docs/user/{slug}.md |
Track selection starts from "who reads it"—the same feature often needs both: API changes go into the dev-guide, and the corresponding user operations go into the user-guide.
Path
docs/dev/anddocs/user/are default conventions; if the project already has its own docs structure, follow the project—confirm before starting.
Trigger timing
| Situation | Description |
|---|---|
| End of feature-acceptance | Proactively push: if Section 2 of the plan (interface contract) has changes, ask "Do you need to update the dev-guide?"; if Section 1 (user-visible behavior) has changes, ask "Do you need to update the user-guide?" |
| User proactively triggers | "write docs", "guidedoc", "add a developer guide" |
| After onboard is complete | A new repository can trigger completion of the basic documentation skeleton |
A one-sentence proactive push is enough; if the user says "no need", do not mention it again—pushing multiple times makes users feel the AI is adding drama.
Paths involved
guidedoc artifactsare not under .codestable/ —guides are publishable artifacts for external readers and are separate from spec artifacts.——Guides are publishable deliverables for external readers, separate from spec artifacts.
- dev-guide →
docs/dev/{slug}.md - user-guide →
docs/user/{slug}.md
File naming {slug}.md(English lowercase hyphenated,no date prefix)—guides are continuously updated and managed by topic.
Retrieval:
python .codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
python .codestable/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}
YAML frontmatter
---
doc_type: dev-guide | user-guide
slug: {英文连字符}
component: {关联模块名或 feature slug}
status: draft | current | outdated
summary: {一句话描述涵盖什么}
tags: []
last_reviewed: YYYY-MM-DD
---
status three states:draft pending review;current currently valid;outdated the corresponding code has changed but the documentation has not kept up (keep the original text, mark it, and push an update).
Documentation format
dev-guide body structure
## 概述
一段话描述功能定位和适用场景。
## 前置依赖
集成此模块所需的环境、依赖或配置(如有)。
## 快速上手
最小可运行示例。代码优先文字辅助。
## 核心概念
(可选)理解接口 / API / 模块行为所需的关键术语和设计决定。
## 接口参考
主要 API / 配置选项 / 事件 / 钩子。表格或逐项列举。
## 常见场景
2-4 个实际使用场景代码示例,覆盖 happy path 和常见边界。
## 已知限制与注意事项
(可选)边界、性能考虑、已知 bug 绕过方式。
## 相关文档
关联的 user-guide、方案 doc、架构 doc 或外部参考。
user-guide body structure
## 功能简介
一段话描述功能是什么、解决什么问题。
## 前置条件
(可选)使用前的前提(账号权限、需先完成的操作)。
## 如何使用
步骤化操作。每步一行,关键操作配截图占位(`` 或注明"此处需截图")。
## 常见问题
Q: ...
A: ...
## 相关功能
(可选)关联功能跳转链接或说明。
Workflow steps
- Clarify the task scope—track (dev / user / both) + coverage scope (new writing or update) + information sources (does the plan doc already exist? Is there already a guide for the same component? Which code needs to be read?)
- Collect inputs—read the plan doc (focus on Section 0 terminology, Section 2 interface contract, Section 1 user-visible behavior) +
search-yaml.pySearch docs/ to confirm whether an existing guide exists. If an existing guide is found, markoutdated→ classify the task asUpdate - Draft——Draft according to the corresponding track structure, frontmatter
status: draft. Constraints: write only content for the target readers——Do not carry over the "implementation notes" or internal design from the solution doc; terminology must match Section 0 of the solution doc; code examples must come from actual code and must not invent interfaces - User review——Present the draft and confirm section by section the coverage / accuracy of the description / whether there is anything readers may not understand
- Finalize——After the user approves: write to the path;
status: current+last_reviewedthe same day; when updating an existing document, make minor edits directly, but for major changes (structural reorganization / adjustment of reader targeting), first leave the old document asstatus: outdatedas a reference and then write a new one
Relationship with other workflows
| Source | Relationship |
|---|---|
cs-feat-accept |
After acceptance, proactively push: push interface changes to dev-guide, and user-visible changes to user-guide |
cs-feat-design |
Section 2 of the solution is the main source of information for dev-guide; Section 1 is the main source of information for user-guide |
cs-onboard |
After a new repository is onboarded, the basic documentation skeleton can be completed |
cs-arch (check) |
When inconsistency between design and code is detected, the corresponding guide should be marked in sync as outdated |
cs-decide |
The technology choices referenced by dev-guide should come from decisions and should not be invented independently |
cs-trick |
If dev-guide usage examples overlap with tricks, cross-reference them instead of writing them again |
cs-libdoc |
Guides reference libdoc entries for detailed reference; libdoc is a parts reference, while guidedoc is a task tutorial |
Common pitfalls
- Copying the "implementation notes" verbatim from the solution doc into dev-guide——that is an internal spec
- Creating a new guide without checking existing guides——there may be a conflict between the two
- After writing,
statusstilldraft——Finalizing must changecurrent - After the code has been updated, the relevant guide is still
current——Should markoutdatedand push the update - dev-guide and user-guide have highly overlapping content——one of them is positioned incorrectly
- Using guides to store spec information (invariants / test constraints / root cause analysis)——this type of content belongs to
.codestable/