智能体项目方法论 yuexiaoliang/dsh-methodology

dsh 方法论：如何在智能体时代构建一个始终可控的软件项目

languages
written by
case study

一门关于使用 AI 编码智能体构建复杂软件项目的双语方法论课程——涵盖架构决策记录（ADR）、运维手册、机械化质量门禁、能力接缝插件架构、微内核设计以及事件溯源状态，提炼自真实世界的 deepseek-harness 项目。

这是一门关于如何启动并持续演进一个复杂软件项目的方法论课程。它提炼自一个真实且极端的案例：deepseek-harness，一个基于插件的智能体 harness，主要由 AI 编码智能体开发，在大约两个月内经历了 12,000+ 次提交、226 个工作区包和 720+ 条决策记录，却始终没有失控。

阅读本课程不需要访问 deepseek-harness 仓库。 每个概念都是自包含讲解的；deepseek-harness 仅作为案例证据出现。如果你确实想对照其来源验证某个说法，附录 A 提供了完整的文件与版本可追溯性。

这个方法解决什么问题

当开发速度从“人类写代码”转变为“智能体写代码”时，瓶颈不再是产出，而是一致性：

- 智能体没有跨会话记忆；昨天的设计理由今天已不复存在；
- 智能体从现有代码中推断未写明的规则，而这种推断总是比任何人本意都更偏保守；
- 代码和测试记录了什么发生了变化，但没有记录为什么这个方案胜出或放弃了什么。

该方法的答案是四个外化：将记忆外化为决策记录，将技艺外化为操作流程，将纪律外化为机械门禁，将架构外化为可复制的扩展模式。

同样的方法也适用于纯人类团队——它只是把“优秀团队过去靠隐性知识维持的东西”变成了成文制度。智能体只是让缺失制度的代价更快显现出来。

目录

| 章节 | 内容 |
| 第 1 章 背景与问题 | 智能体驱动开发的三个结构性问题 |
| 第 2 章 基础：第一天该做什么 | 世界观文档、框架所有权、第一天就设置门禁 |
| 第 3 章 架构方法论 | 微内核、事件语义、能力接缝、事件溯源、组合层 |
| 第 4 章 决策记录系统 | 如何设计一个真正能够被执行的 ADR 系统 |
| 第 5 章 将流程操作化 | 将反复出现的工作流转化为可执行的运行手册 |
| 第 6 章 机械门禁与最小充分证据 | CI 负责完整矩阵；本地只运行与差异相关的证据 |
| 第 7 章 演进节奏与三个案例研究 | 构建—裁剪—归档；一个前端包的完整生命周期 |
| 第 8 章 采用指南 | 面向第一天、第一周和持续运营的可操作清单 |
| 第 9 章 陷阱 | 真实陷阱及其补救措施 |
| 第 10 章 rc.8 案例研究 | 实验性能力孵化、表层裁剪、基于证据的 CI 调优 |
| 附录 A 可追溯性 | 案例数据、概念来源、版本锚点（可选阅读） |

如何使用

- 学习方法论：按顺序阅读；每一章都以判断标准或采用行动结尾。
- 采取行动：直接跳到第 8 章的清单，遇到不熟悉的概念时再查阅前面的章节。
- 进行验证：附录 A 将每个概念映射到 deepseek-harness 仓库中的文件、日期和版本。

本课程是如何制作的

本课程由 Kimi K3 + Codex 编写，由人类设定方向并做出判断。

制作过程本身就是第 4 章方法的一次应用——先解构，再提炼：

1. 源研究：从 deepseek-harness 的 .agents 目录出发，我们阅读了其决策记录（720+）、操作流程（11）、架构文档以及完整的 git 历史（12,000+ 次提交），从文件名日期和提交序列重建项目的构建阶段；
2. 生命周期追踪：我们选取了有代表性的能力线（shell 接缝、TUI 的完整生命周期、Agent Teams 在 rc.8 中的孵化），按时间顺序阅读其决策记录，以对照真实演进验证方法论；
3. 提炼：观察结果被改写为自成一体的章节；正文采用转述而非引用，每一条判断标准都可以在附录 A 中追溯到具体的决策记录、日期和版本；
4. 事实核验：每一处文件引用、版本号和统计数据（包数量、提交数量、记录数量）都经过机械检查，并随 deepseek-harness 发布而更新（目前跟踪 0.1.0-rc.8）。

维护

本仓库践行其所教授的内容。面向贡献者和代理的维护规则位于 AGENTS.md；定期更新流程——针对更新的 deepseek-harness 发布重新同步——是 maintenance/SYNC.md，由机械门禁 node maintenance/verify.mjs 提供支持。

许可证

本课程正文是原创的方法论提炼。案例事实来自对 deepseek-harness 仓库的研究；来源列于附录 A。

关键词：AI 编程智能体、智能体开发方法论、架构决策记录（ADR）、插件架构、微内核、事件溯源、CI 质量门禁、最小充分证据、LLM 智能体框架、中英双语教程、deepseek-harness、AI 编程、agent 开发方法论、架构决策记录、插件化架构、微内核、事件溯源、质量门禁、中英双语教程