CC端到端开发skill：强调项目知识库的同步更新
前言：这篇文章介绍
fully-coding如何处理项目知识库。重点不是“生成更多文档”，而是让代码实现、服务设计、错误码、功能实现概览和菜单迭代文档保持一致。
本博文对应的代码仓库见：(Github)[https://github.com/seedily/claude-coding-skills]
背景
很多项目的技术文档会慢慢失效。原因通常不是没人写文档，而是代码变更和文档变更没有绑定。
常见问题包括：
- 新增接口后服务设计文档没更新。
- 新增错误码后错误码文档没登记。
- 功能实现文档越建越多，最后没人知道哪个是最新的。
- 后台菜单、路由、权限入口变了，但菜单迭代表没有同步。
- 开发方案和最终代码出现偏差，文档仍停留在方案阶段。
fully-coding 把知识库同步放进 Step 8，并在 Step 9 做一致性自检。这样文档不是开发完成后的可选动作，而是交付流程的一部分。
这体现的是 SDD（Specification-Driven Development，规范驱动开发）的思想：规范是第一性产物，代码只是其中一个落地结果。需求、设计、错误码、接口、菜单入口和测试结论都需要以规范化文档存在，后续自动化流程才能稳定读取、判断和继续推进。
project-config.md 统一配置知识库
fully-coding 不把知识库路径写死，而是集中在 project-config.md 中配置。
关键配置包括：
knowledge_dir: "_knowledge"
output_dir: ".dev-log"
requirement_doc: "3.量化交易资讯项目-需求.md"
error_code_doc: "5.服务详细设计（错误码段位分配）.md"
tech_design_glob: "4.技术方案-*.md"
service_design_glob: "5.服务详细设计-*.md"
feature_impl_glob: "6.功能实现-*.md"
feature_impl_template: "6.功能实现（模版）.md"
feature_impl_overview: "6.功能实现（概览）.md"
feature_impl_menu_iteration: "6.功能实现（菜单功能迭代）.md"
menu_client_apps: ["admin-biz-web", "member-biz-web", "APP"]
这种配置方式的好处是：
- Skill 可以迁移到其他项目。
- 文档命名规则集中维护。
- 角色文件和规则文件只引用
{{config.*}}，不写死项目路径。 fully-coding和fully-coding-batch共享同一份配置。
功能实现文档的复用优先原则
fully-coding 对 6.功能实现-*.md 的生成机制做了专门约束。
Step 4 生成开发方案前，架构师必须先读取：
_knowledge/6.功能实现（概览）.md
然后将本次功能与概览表中的字段匹配：
- 功能名称。
- 所属模块 / 领域。
- 实现文档路径。
- 关联菜单 / 入口。
如果已经存在同名、相近或同一菜单 / 核心功能下的实现文档，优先复用该文档，并在后续步骤中追加或修订功能描述。
只有两种情况才新建文档：
- 概览表和既有
6.功能实现-*.md都找不到可承载本次功能的文档。 - 本次功能非常核心且开发量大，继续追加到既有文档会导致职责混杂或文档过长。
这条规则解决的是知识库碎片化问题。
新建功能实现文档的命名规范
如果确实需要新建功能实现文档，必须参考：
_knowledge/6.功能实现（模版）.md
并使用统一命名：
6.功能实现-[管理web|会员web|会员app]-[一级菜单|核心功能]-[二级菜单].md
例如：
6.功能实现-管理web-系统管理-角色管理.md
6.功能实现-会员web-智能助手.md
6.功能实现-核心功能-数据采集与质量治理.md
无二级菜单时，可以使用能准确表达入口或能力的核心功能名作为最后一段。非前端入口的后端核心能力，则按主要使用端选择端标识；无法归属时，需要在 codingLog.md 记录判断依据。
功能实现文档必须包含什么
新建或更新功能实现文档时，不能只写几句说明。Step 4 要求文档至少覆盖：
- 功能概述。
- 时序图 / 流程图。
- 接口设计：URL、方法、入参、出参、错误码。
- 数据模型：表、字段、Redis Key。
- 核心逻辑步骤。
- 异常处理。
如果涉及写操作，还要说明幂等性、并发和异常边界。
这让功能实现文档不只是“功能说明”，而是可以指导开发和评审的设计文档。
从交接角度看，它还承担了“下一步输入”的职责。开发者可以基于它实现代码，Reviewer 可以基于它检查偏差，Step 8 可以基于它反向同步知识库。文档写得越规范，自动化流程越容易判断当前步骤是否完成。
Step 8 的反向同步
Step 4 写的是方案，Step 5 写的是代码。到了 Step 8，架构师要对比最终代码和方案，并反向更新知识库。
Step 8 的更新范围包括：
| 变更类型 | 必须更新 |
|---|---|
| 新增或修改功能实现文档 | 对应 6.功能实现-*.md + 6.功能实现（概览）.md |
| 修改功能状态、范围、接口、涉及服务 | 功能实现文档 + 概览文档 |
| 新增菜单、页面、路由、权限入口 | 6.功能实现（菜单功能迭代）.md |
| 新增错误码或领域枚举 | 错误码文档 + 对应功能实现文档 |
| 服务接口、依赖关系或调用方式变化 | 服务设计文档 + 对应功能实现文档 |
这就是 fully-coding 的文档同步触发矩阵。
错误码同步
项目使用错误码格式：
[L][CC][SS][D]
Step 4 设计错误码时，优先使用错误码文档中已有的 [L][CC] 枚举，并使用当前系统的 SS 和 D 段位。
如果需要新增错误码，Step 4 先记录：
新增 [L][CC] = 取值 / 含义 / 使用场景
Step 5 实现时记录实际使用情况。Step 8 再反向更新错误码文档。
这样做可以避免代码里新增了错误码，但公共错误码文档没有登记。
菜单功能迭代同步
如果本轮改动涉及任一客户端的菜单、页面、路由、权限或导航入口，就必须更新：
_knowledge/6.功能实现（菜单功能迭代）.md
这个文档不展开接口和领域模型细节，而是维护入口级索引。它至少应该记录：
| 菜单/页面名称 | 端 | 路由/入口 | 关联功能实现文档 | 权限点/角色 | 状态 | 变更说明 | 最近更新时间 |
|---|
它的作用是回答一个很现实的问题：
这个页面、菜单或权限入口，对应的功能实现文档在哪里？
Step 9 的一致性自检
Step 9 不修改代码，只做自检、必要文档补充和建议记录。
它会检查：
- Step 5 代码变更与 Step 8 文档更新是否匹配。
- 新增或修改
6.功能实现-*.md时，功能实现概览是否同步。 - 新增功能实现文档前，是否先检索概览并确认没有可复用文档。
- 新文档命名是否符合规范。
- 菜单、页面、路由、权限入口变更时，菜单功能迭代表是否同步。
- 概览表中的实现文档路径是否真实存在。
- 功能实现文档引用的接口和错误码是否与代码、服务设计、错误码文档一致。
如果遗漏可以自动补充，则记录到 Step 8 的“代码与文档偏差说明”；如果变更量较大，则写入 suggestion.md。
一次完整同步的流程
和普通文档维护的区别
普通文档维护通常依赖开发者自觉。fully-coding 则把文档维护变成流程契约。
它要求文档在每个关键步骤都具备明确结构，而不是最后补一段总结。这样每个步骤的产物都能交接给后续步骤，也能在长周期任务中被恢复进程重新读取。
区别在于：
| 维度 | 普通维护 | fully-coding |
|---|---|---|
| 何时更新 | 开发者记得时 | Step 8 强制检查 |
| 是否复用既有文档 | 靠人工判断 | Step 4 必须先查概览 |
| 错误码是否同步 | 容易遗漏 | Step 4/5 记录，Step 8 更新 |
| 菜单入口是否同步 | 容易遗漏 | 命中触发矩阵必须更新 |
| 文档路径是否有效 | 靠人工检查 | Step 9 自检 |
总结
fully-coding 的知识库同步机制，核心不是多写文档，而是减少文档漂移。
它通过几条规则实现：
- 用
project-config.md统一知识库路径和文档名。 - Step 4 先查功能实现概览，优先复用既有文档。
- 只有缺失或核心大功能时才新建功能实现文档。
- 新文档必须参考模板并遵循命名规范。
- Step 8 根据最终代码反向同步服务设计、错误码、功能实现、概览和菜单迭代。
- Step 9 做一致性自检。
这些规则让文档成为可交接、可验证的规范，而不只是项目资料。它们也是 fully-coding 能够进一步自动化、并支撑超长周期编程的基础。
这套机制让 fully-coding 不只是写代码的工具，而是把代码、设计和知识库一起交付的工具。
浙公网安备 33010602011771号