技术方案完成评审,并不意味着设计阶段的工作已经全部结束。对于正式软件项目,评审通过的方案还需要转化为开发人员能够使用、测试人员可以验证,并且在后续修改中能够持续维护的设计资料。
过去,项目设计文档主要供团队成员阅读。开发人员通过文档了解模块、接口和数据结构,不清楚的地方再向架构师确认。随着 Coding Agent 逐渐参与实际开发,这些文档又增加了一个新的使用者。Agent 可以阅读代码、查询文档、修改文件和执行测试,但它并不了解项目长期积累的业务约定。如果设计资料不完整,或者与现有代码存在冲突,Agent 就可能基于错误的上下文进行修改。
因此,设计文档不仅要让人看得懂,还需要让项目中的 AI 工具能够准确找到、理解并使用,同时保证文档与实际系统保持一致。
一、为什么有些设计文档很难持续使用?
在不少软件项目中,设计阶段会形成完整的概要设计和详细设计文档,但开发开始以后,这些文档逐渐失去作用。常见情况包括:架构设计保存在 Word 中,接口定义维护在另一套平台,数据库设计由开发人员自行更新,部分技术决策只存在于聊天记录中。项目初期问题并不明显,但随着功能持续修改,设计文档和实际代码之间的差异会越来越大。例如,一个接口最初约定同步返回处理结果,后来因为性能问题改成异步任务,代码和接口都已经调整,但设计文档仍然保留原来的描述。
对于开发人员来说,可以通过阅读代码发现变化;但 Coding Agent 如果读取了旧文档,可能继续按照同步接口进行开发,甚至把已经修复的问题重新引入系统。因此,设计文档需要解决三个实际问题:
能够找到。 开发人员和 Agent 知道某项设计信息应该从哪里获取。
能够理解。 文档清楚描述系统结构、业务规则和技术约束,而不只是罗列实现步骤。
能够保持更新。 代码、接口或数据结构发生重要变化以后,相关设计资料能够同步调整。
这三个要求,比单纯增加文档篇幅更重要。
二、按用途组织设计资料,避免所有内容放进一个文档
传统项目经常把系统架构、模块设计、接口说明和数据库结构放进一份很长的设计说明书。这种方式适合形成正式交付材料,但在日常研发中不一定方便使用。开发人员修改某个模块时,通常只需要与当前任务相关的设计内容;Agent 也是如此。因此,可以在保留正式设计说明书的同时,将经常使用的技术资料按用途进行组织。
| 设计资料 | 主要内容 | 主要用途 |
|---|---|---|
| 系统架构 | 系统边界、服务关系、技术组件 | 理解整体结构 |
| 模块设计 | 模块职责、流程、业务规则 | 指导功能开发 |
| 接口契约 | API、参数、返回值、错误码 | 前后端与系统集成 |
| 数据设计 | 表结构、关联关系、数据约束 | 数据处理和兼容性 |
| 技术决策记录(ADR) | 采用什么方案、为什么采用 | 理解历史设计 |
| 运行说明 | 部署、配置、监控、恢复方式 | 运维与问题处理 |
这些资料不一定要全部采用 Markdown,也不需要彻底改变企业原有的文档管理方式。对于与代码关系密切的部分,可以采用 Markdown、OpenAPI、SQL 迁移脚本等容易进行版本管理和自动检查的格式;对于面向客户的正式设计文档,仍然可以使用 Word 或 PDF。关键是明确不同资料的用途,并尽量避免同一项设计规则在多个地方独立维护。
三、案例:离职成员文件交接的设计文档如何组织
继续使用 BaseMetas 云文档中的离职成员文件交接功能作为示例。以下结构用于说明设计文档的组织方式,并不代表产品现有的实际代码和文档目录。在上一篇中,我们假设经过技术评审,选择了“异步任务分批处理”的实现方案。此时需要将评审结论转化为开发可以使用的设计内容。可以先建立一份模块设计说明:
模块:离职成员文件交接
| 项目 | 设计内容 |
|---|---|
| 关联需求 | REQ-004、REQ-006 |
| 主要职责 | 将离职成员拥有的个人文件转移给指定接收人 |
| 执行方式 | 后台异步任务,分批处理 |
| 关联决策 | ADR-008 |
| 相关模块 | 成员服务、文件服务、权限服务、任务中心 |
| 关键约束 | 团队空间资源不改变归属 |
| 完成条件 | 待交接资源全部成功处理 |
| 异常处理 | 记录失败资源,支持重新处理 |
| 相关测试 | TC-104、TC-105、TC-106 |
有了这份模块设计,开发人员和 Agent 就不需要每次从完整的需求说明书和技术评审记录中重新理解业务。进一步,还需要将关键规则明确写出来。例如:
RULE-001
只处理离职成员拥有的个人资源。
RULE-002
团队空间中的资源不改变 Owner。
RULE-003
重复执行交接任务,不得重复转移已成功的资源。
RULE-004
全部待交接资源完成处理前,不允许删除原成员。
这些规则需要与已经确认的需求保持一致。它们不仅是设计说明,也可以成为开发检查和测试验证的依据。对于异步任务,还可以单独定义状态模型:
CREATED
↓
RUNNING
├── COMPLETED
└── PARTIAL_FAILED
↓
RETRY
↓
RUNNING
状态名称和转换条件应以项目实际设计为准。这里特别需要说明哪些状态允许重新执行、哪些状态允许删除成员,以及任务失败后如何恢复。相比几十页连续文字,这类结构化设计更容易用于具体开发任务,也方便 AI 在修改相关功能时获取关键约束。
四、设计文档与代码应当建立明确的关联
模块设计写得清楚,只解决了如何理解系统的问题。进入开发以后,还需要知道设计对应哪些接口、数据结构和代码模块。例如文件交接功能,可以建立以下关系:
REQ-004 文件交接
↓
模块设计
member-handover.md
↓
技术决策
ADR-008
↓
接口定义
Handover API
↓
数据结构
HandoverTask
↓
代码实现
File Service / Task Service
↓
测试用例
TC-104 / TC-105 / TC-106
这样一来,开发人员修改交接逻辑时,可以从模块设计找到业务约束,再根据接口定义、数据设计和代码实现开展工作。测试人员也可以根据这些关联确认正常交接、团队空间资源处理和失败重试是否得到覆盖。对于 Coding Agent,这些关联同样重要。它能够从当前任务定位到相关资料,而不必在整个项目中进行无目标搜索。
需要注意的是,文档关联不等于在每份资料中复制大量相同内容。更合理的方式是使用稳定编号、文档路径和引用关系,减少重复维护。
五、给开发人员和 Agent 一个统一的文档入口
设计资料逐渐增多以后,新的问题就变成:从哪里开始查找?对于采用 Git 管理代码的项目,可以使用一个轻量的文档目录:
project/
├── README.md
├── AGENTS.md
│
├── docs/
│ ├── README.md
│ │
│ ├── architecture/
│ │ └── overview.md
│ │
│ ├── modules/
│ │ └── member-handover.md
│ │
│ ├── decisions/
│ │ └── ADR-008.md
│ │
│ ├── contracts/
│ │ └── openapi.yaml
│ │
│ ├── data/
│ │ └── file-owner.md
│ │
│ └── operations/
│ └── handover-runbook.md
其中,docs/README.md 可以作为文档导航,说明项目有哪些重要设计资料,以及各自的维护位置。AGENTS.md 则可以用于记录 Coding Agent 在当前代码仓库中需要遵循的执行约定,例如项目结构、构建命令、测试方式、编码规范和文档入口。例如:
# Project Guidelines
项目技术栈:Java 21 / Spring Boot
设计资料:
- 系统架构:docs/architecture/
- 模块设计:docs/modules/
- 技术决策:docs/decisions/
- API 契约:docs/contracts/
开发要求:
- 修改业务规则前先阅读对应模块设计
- 不允许擅自改变已确认的权限规则
- 接口发生变化时同步更新 API 契约
- 完成代码修改后执行相关测试
- 提交结果时说明涉及的设计文档
这里要区分两类资料的用途:设计文档负责说明系统是怎样设计的,Agent 指引负责说明在这个项目中应该怎样开展工作。AGENTS.md 不应该替代完整的技术设计,也不适合把几十页架构说明全部复制进去。保留简洁的执行规则和文档入口,通常更加容易维护。
需要说明的是,不同 Coding Agent 对项目指引文件的识别方式可能不同,因此应按实际工具的机制进行配置。对于已有企业知识库的项目,也可以保留原有文档平台,通过统一索引、权限控制和关联链接提供设计资料,不必为了使用 AI 而将所有资料重新迁移到 Git。
六、设计发生变化后,如何保持文档和代码一致
设计文档最容易失去价值的原因,不是最初写得不完整,而是后续没有跟着系统变化。例如文件交接功能最初采用异步分批处理,后来因为性能要求调整,引入消息队列分发任务。代码已经完成改造,但模块设计仍然描述由单个后台任务执行,Agent 下一次读取时就可能使用过时的架构信息。因此,应当把必要的文档更新纳入代码变更流程。并不是每次修改代码都需要更新设计文档,但出现以下变化时,通常应该同步检查对应资料:
| 发生的变化 | 需要检查的文档 |
|---|---|
| 业务规则调整 | 模块设计、需求关联、验收标准 |
| API 参数或行为变化 | 接口契约、调用说明 |
| 数据结构变化 | 数据设计、迁移说明 |
| 模块职责或依赖变化 | 架构设计、模块设计 |
| 关键技术方案变化 | ADR、相关模块设计 |
| 部署和运行方式变化 | 部署文档、运维说明 |
对于使用 Git 的团队,可以在 Pull Request 中增加一个简短检查项:
[ ] 本次修改不影响设计文档
[ ] 已更新相关设计文档
[ ] 已更新接口或数据契约
[ ] 已补充相关验证
这里的重点不是增加审批,而是要求开发人员和 Agent 在完成修改时判断:本次代码变化是否使现有设计说明失效?适合自动检查的内容,例如 OpenAPI 格式、文档内部链接及接口契约变化,可以结合 CI 进行校验;业务规则是否正确、设计决策是否合理,仍然需要对应负责人确认。
七、项目知识库应当使用经过确认的设计资料
随着项目积累的设计内容越来越多,团队可以进一步通过搜索、RAG 或其他知识检索方式,让 AI 更容易获取相关资料。但对于软件项目来说,知识库并不是把所有历史文件全部导入即可。例如一个模块可能同时存在方案初稿、评审修改稿、正式设计以及多个过时版本。如果不加区分,AI 可能检索到旧方案,甚至把已经否决的设计当成当前约束。因此,项目知识库至少需要区分:
| 文档状态 | 使用方式 |
|---|---|
| 草稿 | 用于讨论,不作为正式开发依据 |
| 已批准 | 当前有效设计依据 |
| 已废弃 | 保留历史记录,不用于当前实现 |
| 已被替代 | 指向新的有效版本 |
对于重要设计,还应保留责任人、关联版本和技术决策记录。这里尤其需要明确“有效来源”。例如 API 的正式定义维护在 OpenAPI 文件中,那么其他文档应引用该契约,而不应该分别维护一套可能不一致的接口参数说明。同样,已经作废的技术方案可以继续保留在 ADR 中,用于解释历史决策,但不应作为当前开发指令。这样知识库才能帮助开发人员和 Agent 找到正确的项目上下文,而不是把历史资料中的差异继续带入新代码。
八、设计文档不必复杂,关键是能够持续维护
对于中小型软件项目,没有必要为了 AI 引入一套庞大的设计文档体系。可以从三项工作开始。
首先,建立统一入口。 让开发人员和 Agent 知道系统架构、模块设计、API、数据结构和技术决策分别在哪里维护。
其次,对核心模块使用固定模板。 至少包含关联需求、模块职责、主要流程、业务约束、接口与数据、异常处理及验证方式。
最后,把文档同步纳入日常开发。 只要代码变化影响了正式设计,就要求在提交变更时完成必要的文档更新。
对于文章中的文件交接模块,一份比较实用的最小设计模板可以是:
| 内容 | 填写要求 |
|---|---|
| 模块名称 | 离职成员文件交接 |
| 关联需求 | REQ-004、REQ-006 |
| 主要职责 | 处理个人文件交接 |
| 核心流程 | 异步任务、分批处理 |
| 关键规则 | 团队空间不迁移、重复执行安全 |
| 接口与数据 | 对应 API、任务和文件归属数据 |
| 异常处理 | 失败记录、重试、恢复 |
| 验证方式 | 相关测试用例与检查条件 |
| 技术决策 | ADR-008 |
| 维护信息 | 负责人、状态、适用版本 |
这些内容足够清楚以后,复杂系统可以再按实际需要增加时序图、性能约束和部署说明。设计文档最终应该帮助团队减少沟通和返工,而不是形成新的文档维护负担。
九、结语:让设计文档成为研发过程中的有效依据
AI 参与软件开发以后,设计文档的使用范围正在扩大。它不仅服务于架构师和开发人员,还会持续为 Coding Agent、测试工具和项目知识检索提供上下文。因此,设计文档需要在原有业务和技术说明的基础上,进一步明确模块职责、接口契约、数据约束、关键决策以及与代码和测试的关联关系。但这并不意味着设计文档需要写得越来越多。
对于正式软件项目,更有价值的是设计资料能够准确找到、内容经过确认、关键规则清楚,并且在系统发生变化后能够及时更新。当开发人员能够根据文档理解系统,Agent 能够读取正确的技术约束,测试人员能够找到对应的验收依据时,设计文档才真正发挥了作用。最终需要建立的也不是两套分别供人和 AI 阅读的设计资料,而是一套由项目团队共同维护、可以被不同角色和工具持续使用的设计依据。
下一篇:AI 编程进入项目后,开发任务和代码交付怎么管?
技术设计明确以后,接下来进入开发实现阶段。
Coding Agent 已经能够阅读项目、修改多个文件、执行构建和测试,但正式项目仍然需要将需求拆分成明确的开发任务,并控制代码修改范围、Review、测试和合并过程。
下一篇将围绕实际开发任务,讨论如何组织 AI 参与编码,以及开发负责人如何管理 Agent 产生的代码变更,确保最终结果能够进入正常的软件交付流程。
