用途:把代码与 spec 转成面向读者的可发布指南,分两条轨道——dev-guide 面向贡献者、集成方和下游开发者,输出 docs/dev/{slug}.md;user-guide 面向终端用户,输出 docs/user/{slug}.md。轨道按“谁读”选择,同一功能常需两份。
主要能力:指导编写含 YAML frontmatter(doc_type、slug、component、status、summary、tags、last_reviewed)的文档,status 分 draft、current、outdated;规定 dev-guide 结构(概述、前置依赖、快速上手、核心概念、接口参考、常见场景、已知限制、相关文档)与 user-guide 结构(功能简介、前置条件、如何使用、常见问题、相关功能);提供草稿、用户 review、落盘流程,更新时小修直接改、大改先标 outdated。
使用方式:开始前先执行 CodeStable preflight,读 .codestable/attention.md;缺失则先 cs-onboard。检索已有指南可用:python .codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current 或 --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}。
适用场景:acceptance 后接口契约变更推 dev-guide、用户可见行为变更推 user-guide;用户说“写文档”“补一份开发者指南”;新仓库 onboard 后补基础文档骨架。
限制:指南是外部产物,不放在 .codestable/ 下;不搬运 spec 内部实现提示、不变量或测试约束;代码示例须来自实际代码,不虚构接口;不写 spec 信息;路径约定默认 docs/dev 与 docs/user,项目已有结构以项目为准;用户拒绝主动推送后不再重复提议。官方未提供更多收费或平台信息。