项目开发协作文档能力

📖 AI Agent 实战系列 06

2026-06-17

💡概述

本文分析一个面向 Claude Code 的项目开发协作能力：project-development-collaboration。它不以直接生成代码为首要目标，而是先将需求、设计、接口、测试和验收材料整理为可追踪的标准化文档。

一、先处理“需求不可执行”

在 AI Coding 场景中，代码生成能力不是唯一瓶颈。更常见的问题是输入不稳定：口头需求、零散截图、过期文档、隐含业务规则同时存在。

project-development-collaboration 的处理方式是：先建立文档骨架、编号体系、模板映射和质量门禁，再决定是否进入编码阶段。

设计定位

这个 Skill 的核心是建立协作协议：哪些信息需要确认，哪些内容允许暂缺，编号如何维护，何时只输出计划，何时可以进入实现。

二、能力定位：标准化文档，不是代码生成器

能力定义刻意划清了边界：

默认先生成文档或计划，不直接修改业务代码。

只有用户明确要求“开始实现”“修改代码”“按计划开发”时，才进入代码实现阶段。

不直接生成 Word 文档，也不替代项目既有的 CLAUDE.md、README、架构规范和测试规范。

不在用户未确认输出目录和写入权限前批量创建文件。

因此，它属于前置治理型 Skill：先整理上下文、边界、计划和验收依据，再决定是否执行代码变更。

三、常见请求如何处理

请求

“帮我做一个用户登录功能”

处理方式

先拆成功能文档包，明确产品设计、需求规格、页面原型、接口、测试和验收。

请求

“根据这个需求改代码”

处理方式

先生成前后端开发计划，列出文件清单、接口字段、风险与待确认问题。

请求

“把老项目文档整理一下”

处理方式

进入反向工程模式，以代码为真相源，旧文档仅作参考，差异显式记录为 GAP / ISS。

四、总体架构：三层组成

1. 能力入口层

SKILL.md 定义启用场景、工作流程和边界，用于稳定识别任务类型，减少自由发挥。

2. 知识模板层

references/ 保存流程、模板、编号约定和反向工程指引，沉淀可复用的文档结构。

3. 质量校验层

scripts/ 检查能力包和输出目录，将部分一致性要求转化为可检查规则。

目录结构

project-development-collaboration/

├── SKILL.md

├── INSTALL.md

├── references/

│　├── 00-工作流程指引.md

│　├── 01-产品设计说明书模板.md

│　├── 15-编号与命名约定.md

│　└── 16-反向工程整理指引.md

└── scripts/

五、五种输出模式

能力定义了 A~E 五种输出模式，对应项目初始化、功能拆解、开发计划、测试验收和存量项目整理。

模式 A：初始化项目级标准化文档

生成项目级 00~10 文档，包括项目总览、产品设计、需求规格、页面原型、UI 规范、前后端说明、API 清单、测试计划、验收清单和后续规划。

模式 B：创建功能级文档包

采用“一个功能一个目录”的方式，将每个功能拆成 README、产品设计、需求规格、页面原型、UI 补充、前后端说明、API 说明、测试用例和验收清单。

模式 C：根据已确认文档生成开发计划

连接文档与实现，输出前端文件清单、后端文件清单、API 路径、数据结构、权限控制、异常处理、联调步骤和待确认问题。默认只输出计划，不修改代码。

模式 D：生成测试与验收材料

覆盖正常流程、空数据、异常、UI、回归测试，并使用 AC-PROJ-XXX 或 AC-F00X-XXX 表示验收项。

模式 E：反向整理已有需求与代码

面向存量项目。以代码、接口、数据库、脚本和测试为准；旧需求与当前代码不一致时记录为 GAP-XXX，代码已知问题记录为 ISS-XXX。

六、功能文档包的结构

功能级文档采用固定目录结构。这样可以保持功能边界清楚，前端、后端、测试和验收围绕同一个功能编号工作。

标准化文档/功能文档/F001-功能名称/

├── README.md

├── 01-产品设计说明.md

├── 02-需求规格说明.md

├── 03-页面原型说明.md

├── 04-UI补充说明.md

├── 05-前端开发说明.md

├── 06-后端开发说明.md

├── 07-API接口说明.md

├── 08-测试用例.md

└── 09-验收清单.md

七、编号系统：可追踪的基础

references/15-编号与命名约定.md 是能力包的编号约束文件。编号用于建立“需求 → 原型 → 接口 → 实现 → 测试 → 验收 → 遗留问题”的追踪链路。

REQ-XXX

需求标识。项目级每条 REQ 一对一映射一个功能；功能级同号同义。

FR-F00X-XXX

功能点。功能级展开，不在项目级需求总览中过度展开。

API-XXX

接口编号。主编号只在项目级 API 清单分配，功能级只能引用或筛选。

TC-XXX

测试用例。正常、空数据、异常、UI、回归按段位分区。

GAP-XXX / ISS-XXX / LEFT-XXX

分别记录文档与代码差距、代码已知问题、验收遗留项。

八、质量门禁：一致性与边界控制

质量门禁用于控制输出漂移。常见风险包括：补入未确认的业务规则、重新分配接口编号、把功能级细节写入项目级文档、用同一个需求号表达不同含义。

需要检查的六类要求

1. 需求、原型、接口、测试、验收之间可追踪。

2. 项目级文档只放全局约定和索引。

3. 功能细节放入功能文档包。

4. 开发计划不超出已确认需求。

5. 不确定信息明确标注为待确认。

6. 编号符合约定，项目扩展前缀必须显式声明。

九、Harness 思维：约束模型工作的环境

从工程化角度看，这个 Skill 属于 Harness Engineering 实践。它不直接改变模型能力，而是约束模型工作的环境。

目录结构 约束输出位置：项目级 00~10 与功能级 01~09 分工明确。

模板 约束输出形态：不同角色和阶段都有对应模板。

编号体系 约束引用关系：避免跨文档语义漂移。

校验脚本 约束交付质量：把部分格式和一致性问题自动化检查。

边界说明 约束执行行为：默认不改代码、不批量写入、不编造不确定事实。

十、人机协作流程：计划、确认、执行

这里使用纵向步骤表达，便于在公众号中阅读：

1. 用户提出项目 / 功能目标

↓

2. AI 阅读项目现状与已有规范

↓

3. 生成文档目录或功能文档包大纲

↓

4. 用户确认

不确认：记录待确认问题并调整；确认：生成标准化文档。

↓

5. 运行或人工执行质量检查

↓

6. 生成开发计划

↓

7. 判断是否进入实现

未明确要求实现：停在计划与验收依据；明确要求实现：进入代码实现与验证。

该流程将输出拆分为可审查节点，避免从需求直接跳到代码。复杂项目中，多阶段确认比单轮生成更稳妥。

十一、设计要点

自包含参考资料

references/ 是自包含副本。能力包既可以复制到用户级 Claude skills 目录，也可以放入项目的 .claude/skills/ 中随仓库携带。

尊重目标项目已有规范

能力要求先阅读 CLAUDE.md、README、技术栈配置和已有文档，并声明目标项目已有规范优先于通用模板。

把不确定性显式化

信息不足时，不强行补全，统一写入“待确认问题”。不确定性需要被记录，而不是被隐式假设覆盖。

反向工程模式面向存量项目

模式 E 将代码、旧文档、差距和已知问题纳入同一个整理流程，适用于文档滞后的存量系统。

十二、后续改进方向

更细的模板裁剪机制：不同技术栈、不同项目规模可启用不同文档子集，避免小项目负担过重。

文档图谱化：将 REQ、FR、API、TC、AC、GAP、ISS 抽取成结构化索引，支持自动追踪和影响分析。

与代码验证更深集成：根据功能文档自动生成测试清单，并把实际测试结果回写到验收材料。

多角色 Agent 协作：产品 Agent、架构 Agent、测试 Agent、代码 Agent 基于同一编号体系协同。

历史项目治理报告：模式 E 可进一步输出项目健康度、文档覆盖率、接口覆盖率和差距统计。

十三、小结

project-development-collaboration 的价值不在于提供 Markdown 模板，而在于将项目协作规则固化为 Claude Code Skill：触发场景、输出模式、编号约束、质量门禁、反向工程流程，以及明确的行为边界。

普通 Prompt 更接近一次性指令；该能力更接近可复用的协作协议。它将 AI Coding 放入可追踪、可确认、可验收的工程流程中。

AI Agent 实战系列 · 006

最后更新：2026-06-17