团队Vibe Coding开发指南 - DDAD方法论

Appearance

文档工具体系与树状结构设计 ​

在“团队 Vibe Coding”中，文档不再是代码的附属品，而是整个开发流程的“单一事实来源”（Single Source of Truth）。它既是团队成员之间沟通的桥梁，也是喂养给AI的最重要的“上下文食粮”。因此，设计一个科学的文档工具体系和信息结构至关重要。

“文档即代码”（Docs as Code）的核心理念 ​

我们推崇“文档即代码”的理念，即像管理代码一样管理文档。这意味着文档应该具备以下特性：

  • 版本控制：所有文档都应纳入Git进行版本管理，每一次变更都有记录、可追溯。
  • 代码审查：重要的文档（如架构设计、API规范）应像代码一样，经过Pull Request (PR) 和 Code Review流程。
  • 自动化：文档的格式检查、链接校验、发布部署都应自动化完成。
  • 纯文本格式：优先使用Markdown等纯文本格式，便于版本比对和程序处理。

这种方式确保了文档的严谨性，并使其能与开发工作流无缝集成。

文档工具选型对比 ​

选择一个合适的文档平台是基础。不同的工具有不同的侧重点。

工具VitePress / Docusaurus (推荐)GitBookNotionConfluence
一句话总结开发者友好的“文档即代码”最佳实践产品化的在线知识库，体验优雅灵活强大的All-in-One协作空间企业级的传统文档协作平台
核心优势- 与Git完美集成
- 高度可定制
- 性能极佳
- 纯文本，对AI友好		- UI/UX出色
- 支持多人实时协作
- 版本历史清晰		- 数据库功能强大
- 块编辑器极度灵活
- API开放		- 与Jira生态深度集成
- 权限管理完善
- 插件生态丰富
主要缺点- 需要一定的技术配置
- 实时协作能力弱		- 定制性较差
- 导出和迁移不便		- 非纯文本，不便于Git管理
- 结构过于灵活，易混乱		- 编辑体验笨重
- 对Markdown支持不佳
- 价格昂贵
AI协作友好度⭐⭐⭐⭐⭐
纯文本Markdown文件是AI最容易理解和处理的格式。		⭐⭐⭐⭐
提供API，可以集成，但不是原生文本。		⭐⭐⭐
API调用复杂，非结构化内容多，对AI有挑战。		⭐⭐⭐
同Notion，需要通过API集成，处理富文本格式复杂。

我们的建议：

对于技术团队，我们强烈推荐使用 VitePress 或 Docusaurus 这样的静态站点生成器。这正是本书所采用的方式，也是“文档即代码”的最佳实践。它能确保文档与代码库同在，版本同步，且纯文本的格式对AI最为友好。

树状文档结构设计原则 ​

好的结构能让信息井然有序，便于人类和AI快速定位。我们建议采用统一的、可预测的树状结构来组织所有项目文档。

核心原则：

  1. 按项目组织：每个项目或大型模块都有其独立的根文档目录。
  2. 按类别分层：在项目内部，按文档性质（如需求、设计、决策、复盘）创建子目录。
  3. 统一命名规范：使用简洁、语义化的英文命名文件夹和文件名（如01-requirements, 02-design）。使用前缀数字有助于排序。
  4. 入口文件 README.md：每个目录下都应有一个README.md或index.md文件，作为该目录的索引和摘要。

推荐的文档树状结构示例 ​

这是一个推荐用于新项目的文档结构模板，可以直接在你的Git仓库中创建：

project-root/
└── docs/
    ├── 00-vision-and-scope/
    │   ├── README.md
    │   └── vision-statement.md
    ├── 01-requirements/
    │   ├── README.md
    │   ├── user-stories/
    │   └── functional-specs/
    ├── 02-architecture-and-design/
    │   ├── README.md
    │   ├── system-architecture.md
    │   ├── adrs/  # Architecture Decision Records
    │   │   ├── README.md
    │   │   └── 001-use-postgresql-database.md
    │   └── api-design/
    ├── 03-processes-and-conventions/
    │   ├── README.md
    │   ├── coding-style-guide.md
    │   └── git-workflow.md
    ├── 04-meeting-notes/
    │   ├── README.md
    │   └── 2025-09-02-iteration-planning.md
    └── 05-retrospectives/
        ├── README.md
        └── sprint-1-retro.md

为什么这个结构对AI友好？

  • 可预测性：AI可以通过文件路径快速推断出文档的类型和内容。例如，它知道docs/02-architecture-and-design/adrs/下的文件是重要的架构决策。
  • 上下文关联：当AI处理一个功能时，它可以被引导去阅读01-requirements和02-design目录下的相关文档，从而获得完整的上下文。
  • 易于索引：这种结构化的信息非常容易被索引和检索，无论是被Cursor这样的编辑器，还是被后文将要介绍的MCP服务器。

本节小结： 科学的文档管理是DDAD成功的保障。通过采纳“文档即代码”理念，选择VitePress等静态站点生成器，并设计一套清晰的树状文档结构，我们可以为团队和AI构建一个稳定、可靠、易于理解的知识库，为高效的上下文工程打下坚实的基础。

下一节： MCP服务器与项目管理集成