coder角色项目知识库简介 #

← 返回AI 实践与思考

1. 定位 #

knowledge/ 是面向日常开发维护的项目知识库，主要用于支持：

• 修改小 bug
• 实现小需求
• 快速理解已有功能
• 快速定位代码入口
• 判断问题类型和分析方向
• 降低改动风险

它的目标不是记录每一次任务过程，而是沉淀稳定、可复用的项目特有知识，让开发者或 Agent 能够更快完成：

理解问题 → 找到对象 → 定位流程 → 确认入口 → 制定修改方案 → 控制风险

2. 目录结构 #

knowledge/
├── README.md
├── writing-guide.md
├── domain/
│   ├── README.md
│   └── terms-map.yml
├── issues/
│   ├── README.md
│   ├── categories/
│   ├── symptoms/
│   └── case-studies/
├── structure/
│   ├── README.md
│   ├── objects/
│   ├── flows/
│   ├── entries/
│   └── repos/
├── implementation/
│   ├── README.md
│   ├── fixes/
│   └── risks/
└── skills/
    └── code_review.md

3. 分层说明 #

3.1 domain/：业务语义层 #

domain/ 负责回答：

用户说的这个东西，在系统里到底是什么？ 其实domain包含的信息很多，但是在当前场景下，其实不需要那么多描述。只要把关键的动作，名词沉淀下来。通过简短描述，就能迅速定位到具体的代码级别语义，而不是通过各种手段去查询，之类的。是省的这个动作的消耗。而不是每次都让ai或者人去漫无目的的搜寻，还可能搜寻不全。

核心文件是：

knowledge/domain/terms-map.yml

terms-map.yml 是用户语言到系统知识的静态映射入口。

它会把用户口头描述、业务词、英文名、别名，映射到对应的结构文档中。

日常使用时，domain/ 是第一步，用于把“用户语言”翻译成“项目里的对象或流程”。

3.2 issues/：问题识别层 #

issues/ 负责回答：

这个现象更像哪一类问题？通常是怎么解决的。 这一层是coder角色的经验模式积累，一般分为哪些问题，通常是什么方案解决。

它用于根据问题描述快速判断问题类型，并且参考现有的方案。

3.3 structure/：代码结构层 #

structure/ 是日常修 bug 和做小需求最常用的目录。

它负责回答：

代码在哪里？对象是什么关系？流程怎么走？入口从哪里进？ 这里其实就是代码上层的一个索引模型了，简单交代了代码结构，和目前的功能，以及源码级别的路由。

structure/ 主要分为三类：

structure/
├── objects/
├── flows/
└── entries/

structure/objects/：静态对象结构 #

用于描述核心业务对象在代码中的静态结构。

structure/flows/：动态流程 #

用于描述一个功能从触发到完成的主链路。完成功能串联的代码语义。

structure/entries/：代码入口 #

用于记录高频功能的代码起点。也就是业务的入口。

3.4 implementation/：实施经验层 #

implementation/ 负责回答：

项目的架构风格，模块约束。全局硬约束，代码军规。 实施层面的约束。

它只在准备实际修改代码时使用。

3.5 writing-guide.md：知识回写规则 #

writing-guide.md 用于判断任务完成后，哪些内容值得沉淀，沉淀在哪，怎么取舍. 这一层其实最难，ai堆文档堆知识都很擅长，但是怎么整理，怎么删除。大部分ai都是抓瞎的，这里主要就是为了限制回写的规则.

4. 静态结构重点 #

从静态结构角度看，本知识库最重要的是：

domain/terms-map.yml  issues/
        ↓             ↓
structure/objects/
        ↓
structure/entries/

5. 后续优化方向 #

其实在最开始建设知识库时，我为它设计了很多动态行为约束和流程。但随着 LLM 和 Agent 能力的不断升级，我逐步放弃了这方面的大量沉淀，直接删除了大部分原先定义的工作流。

原因很简单：我明显地感受到，LLM 和 Agent 本身就在朝这类能力持续演进，而我们再去做这方面的人工微调，边际收益已经越来越低。尤其是对于流程整理这件事，用 LLM 来驱动并不是特别合适；如果某个工作流已经足够清晰、稳定、可复用，那么与其用自然语言去约束，不如直接用代码或脚本将其固化下来，这样通常会更可靠，也更易维护。 另外，AI 基础设施本身几乎每天都在进化。因此，我们做知识沉淀时，应该尽量把重点放在 AI 不擅长自动补足、但对项目真正有价值的部分，也就是项目知识、行业特有知识，以及业务层面的持续积累。 同时，我认为知识库本身也需要继续做减法。增加内容很容易，但删除内容很难；而废话越多，真正有价值的信息密度就越低，反而会造成额外消耗。 接下来的主要方向有两个：

1. 淡化 issue 层的记录 只保留那些特别典型、具有代表性的问题。其他问题仍然应当更多地从代码事实出发进行分析，而不是在 issue 层面做过多堆积。
2. 建立从 design 到 structure 的映射链路 面向较大需求，补充一套更严谨的分析和落地流程，确保设计意图能够清晰映射到系统结构层面。