coder角色项目知识库二 #

← 返回AI 实践与思考

背景 #

在《coder角色项目知识库分享》中，知识库被划分为 domain/、issues/、structure/、implementation/ 等层次，核心目标是沉淀那些 AI 不容易自动补足、但对项目真正有价值的知识：业务语义、典型问题、代码结构、实施约束。

本文聚焦其中 design/ 这一层的建设思路，以及它与分析模型、设计模型、代码实施之间的关系。

design/ 的定位与结构 #

在处理复杂需求的过程中，我有意识地用 design/ 来承载分析阶段的产出。目前核心积累的是两类图：

design/
├── XXXmodule/
│   ├── active/      # 活动图：描述业务流程与行为
│   └── class/       # 领域类图：描述关键概念的静态结构

为什么选活动图而不是序列图 #

之前习惯用序列图，但在 design 阶段，我们还没有详细拆解系统当前的结构，只是在理解需求、规范行为。此时活动图更合适：

• 活动图描述"做什么"，不预设系统内部构造；
• 序列图描述"谁调用谁"，需要提前知道参与对象；
• 在模型尚未细化时，用活动图可以避免过早陷入实现细节。

领域类图的作用 #

活动图中的每个节点，如果涉及当前系统无法直接表达的知识，就需要引入领域类图来补充。例如节点是"解析 .ics 文件"，就需要描述：

• .ics 文件包含哪些信息；
• 信息的组织结构是什么；
• 有哪些扩展信息；
• 每个信息字段用来做什么。

这是纯静态信息的描述。当领域知识清晰后，还应该回头把活动图补充完善。

除了这两类核心信息，也可以加上其他补充材料（md、yaml、json 均可）。但这一步本质上是人在理解需求，图形化的信息密度更高，更便于把握全局。

需求信息的提取 #

需求来源形式多样：口头交流、文档、图片或混合。关键需要提取的是：

1. 活动图：业务流程的行为描述；
2. 领域类图：关键概念的静态结构；
3. 需求背景：包括涉众利益、产品取舍方向。

其中背景信息非常重要，直接影响设计时的权衡。但背景信息非结构化、依赖人的判断，目前还没有纳入知识库，后续再扩充。

从分析模型到设计模型 #

拿着分析层面的模型（活动图 + 领域类图），再结合现有系统的真实结构，进行一轮设计：

分析模型（活动图、领域类图） + 现有系统结构 → 详细设计模型

需要表达清楚：

• 现状是什么；
• 目标是什么；
• 哪些模块、类、方法需要变化；
• 对整体流程有什么影响。

这一步是跟 AI 交互式完成的，最终结果是相对详细的设计模型。

实施阶段 #

拿着详细的设计模型去指挥 AI 完成改动。此时对 AI 的智商要求已经不高，实测 5.4 就能比较高效地完成实施。

这与《AI时代，开发工作流总结》中的阶段划分一致：

与知识库其他层的衔接 #

1. 解决问题链路 #

日常修 bug、做小型改动时，直接按这条链路走：

domain/terms-map.yml          # 业务语义入口
        ↓
structure/                     # 代码结构与关系
        ↓
implementation/                # 实施约束与风险

• 先用 domain/ 把用户语言翻译成项目里的对象或流程；
• 再用 structure/ 定位具体代码、类、方法；
• 最后用 implementation/ 判断架构风格、模块约束、全局硬约束，控制风险。

这条链路不经过 design/。真正解决问题时，基于具体代码和 structure/ 来分析即可，不需要再反查 design。

2. 需求迭代链路 #

design/ 只在每次需求迭代时使用，它的作用是对 domain/ 和 structure/ 织入新信息：

需求输入
    ↓
design/ 分析模型（活动图、领域类图）
    ↓
补充 / 校正 domain/ 和 structure/

• 活动图和领域类图帮助理解需求、澄清业务行为；
• 分析完成后，把沉淀下来的业务语义回写到 domain/；
• 把确认后的代码结构、关系变化回写到 structure/；
• 设计模型本身不长期保存为查询层，逐步淡化。

所以 design/ 不是一个日常查阅层，而是一个** weaving（织入）机制**：在需求迭代时把分析结果织入到更稳定的 domain/ 和 structure/ 中，之后日常开发直接基于后者工作。

沉淀策略的调整 #

总体沉淀思路是：分析模型层面主要沉淀活动图和领域类图；设计模型层面逐步淡化。

原因是：设计模型与代码差别已经不大，真正描述清楚时，差不多就是在规划编程语言级别的模型。这个粒度很难把握——太细了和代码没区别，太粗了又没用。

下一步给 structure/ 层做瘦身：

• 重点关注不同类之间的整体关系；
• 着重沉淀和表达"关系"；
• 每个代码节点只做最简洁的描述和索引。

把知识级别上移：重分析模型，淡化设计模型。因为具体实现细节看源码最快，而整体结构和关系才是 AI 和人一眼难以看清的。后者才是知识库应该沉淀的重心。