ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad-core/tasks/document-project.md

12 KiB
Raw Blame History

记录现有项目

目的

为现有项目生成为AI开发代理优化的综合文档。此任务创建结构化的参考资料，使AI代理能够理解项目背景、惯例和模式，从而有效地为任何代码库做出贡献。

任务说明

1. 初步项目分析

关键： 首先，检查上下文中是否存在PRD或需求文档。如果存在，则用它来将您的文档工作重点放在相关领域。

如果存在PRD：

  • 审查PRD以了解计划中的增强/功能
  • 确定将受影响的模块、服务或区域
  • 仅将文档重点放在这些相关区域
  • 跳过代码库中不相关的部分，以保持文档精简

如果不存在PRD： 询问用户：

“我注意到您没有提供PRD或需求文档。为了创建更专注、更有用的文档，我推荐以下选项之一：

  1. 首先创建PRD - 您希望我在记录之前帮助创建棕地PRD吗？这有助于将文档重点放在相关领域。

  2. 提供现有需求 - 您是否有可以共享的需求文档、史诗或功能描述？

  3. 描述重点 - 您能简要描述您计划的增强或功能吗？例如：

    • ‘向用户服务添加支付处理’
    • ‘重构身份验证模块’
    • ‘与新的第三方API集成’

  4. 记录所有内容 - 或者我应该继续对整个代码库进行综合文档记录？（注意：对于大型项目，这可能会产生过多的文档）

请告诉我您的偏好，或者如果您愿意，我可以继续进行完整的文档记录。”

根据他们的回应：

  • 如果他们选择选项1-3：使用该背景来专注文档记录
  • 如果他们选择选项4或拒绝：继续下面的综合分析

首先对现有项目进行分析。使用可用工具：

  1. 项目结构发现：检查根目录结构，识别主文件夹，并了解整体组织
  2. 技术栈识别：查找package.json、requirements.txt、Cargo.toml、pom.xml等，以识别语言、框架和依赖项
  3. 构建系统分析：查找构建脚本、CI/CD配置和开发命令
  4. 现有文档审查：检查README文件、docs文件夹和任何现有文档
  5. 代码模式分析：抽样关键文件以了解编码模式、命名约定和架构方法

向用户提出这些启发性问题，以更好地了解他们的需求：

  • 该项目的主要目的是什么？
  • 代码库中是否有任何特定领域对于代理理解特别复杂或重要？
  • 您希望AI代理在该项目上执行哪些类型的任务？（例如，错误修复、功能添加、重构、测试）
  • 您是否有任何偏好的现有文档标准或格式？
  • 文档应针对哪个技术细节级别？（初级开发人员、高级开发人员、混合团队）
  • 您是否正在计划特定的功能或增强？（这有助于专注文档记录）

2. 深入代码库分析

关键：在生成文档之前，对现有代码库进行广泛分析：

  1. 探索关键领域：

    • 入口点（主文件、索引文件、应用程序初始化程序）
    • 配置文件和环境设置
    • 包依赖项和版本
    • 构建和部署配置
    • 测试套件和覆盖率

  2. 提出澄清问题：

    • “我看到您正在使用[技术X]。我应该记录任何自定义模式或惯例吗？”
    • “开发人员在此系统中最关键/复杂的部分是什么？”
    • “我应该捕获任何未记录的‘部落知识’领域吗？”
    • “我应该记录哪些技术债务或已知问题？”
    • “代码库的哪些部分更改最频繁？”

  3. 映射现实：

    • 识别实际使用的模式（而不是理论上的最佳实践）
    • 找到关键业务逻辑的位置
    • 定位集成点和外部依赖项
    • 记录变通方法和技术债务
    • 注意与标准模式不同的区域

如果提供了PRD：还要分析增强功能需要更改什么

3. 核心文档生成

[[LLM: 生成一份反映代码库实际状态的综合性棕地架构文档。

关键：这不是一份理想化的架构文档。记录存在的内容，包括：

  • 技术债务和变通方法
  • 不同部分之间不一致的模式
  • 无法更改的旧代码
  • 集成约束
  • 性能瓶颈

文档结构：

[项目名称] 棕地架构文档

引言

本文档记录了[项目名称]代码库的当前状态，包括技术债务、变通方法和实际模式。它作为AI代理进行增强工作的参考。

文档范围

[如果提供了PRD：“专注于与以下内容相关的领域：{增强描述}”] [如果没有PRD：“整个系统的综合文档”]

变更日志

日期 版本 描述 作者
[日期] 1.0 初始棕地分析 [分析师]

快速参考 - 关键文件和入口点

理解系统的关键文件

  • 主入口：src/index.js（或实际入口点）
  • 配置：config/app.config.js、.env.example
  • 核心业务逻辑：src/services/、src/domain/
  • API定义：src/routes/或指向OpenAPI规范的链接
  • 数据库模型：src/models/或指向模式文件的链接
  • 关键算法：[列出具有复杂逻辑的特定文件]

如果提供了PRD - 增强影响区域

[突出显示计划的增强将影响哪些文件/模块]

高层架构

技术摘要

实际技术栈（来自package.json/requirements.txt）

类别 技术 版本 说明
运行时 Node.js 16.x [任何约束]
框架 Express 4.18.2 [自定义中间件？]
数据库 PostgreSQL 13 [连接池设置]

等等...

存储库结构现实检查

  • 类型：[单体仓库/多仓库/混合]
  • 包管理器：[npm/yarn/pnpm]
  • 值得注意的：[任何不寻常的结构决策]

源代码树和模块组织

项目结构（实际）

project-root/
├── src/
│   ├── controllers/     # HTTP请求处理程序
│   ├── services/        # 业务逻辑（注意：用户和支付服务之间的模式不一致）
│   ├── models/          # 数据库模型（Sequelize）
│   ├── utils/           # 混合包 - 需要重构
│   └── legacy/          # 请勿修改 - 仍在使用的旧支付系统
├── tests/               # Jest测试（覆盖率60%）
├── scripts/             # 构建和部署脚本
└── config/              # 环境配置

关键模块及其用途

  • 用户管理：src/services/userService.js - 处理所有用户操作
  • 身份验证：src/middleware/auth.js - 基于JWT的自定义实现
  • 支付处理：src/legacy/payment.js - 关键：不要重构，紧密耦合
  • [列出其他关键模块及其各自的文件]

数据模型和API

数据模型

不要重复，而是引用实际的模型文件：

  • 用户模型：参见 src/models/User.js
  • 订单模型：参见 src/models/Order.js
  • 相关类型：src/types/ 中的TypeScript定义

API规范

  • OpenAPI规范：docs/api/openapi.yaml（如果存在）
  • Postman集合：docs/api/postman-collection.json
  • 手动端点：[列出发现的任何未记录的端点]

技术债务和已知问题

关键技术债务

  1. 支付服务：src/legacy/payment.js 中的旧代码 - 紧密耦合，没有测试
  2. 用户服务：与其他服务模式不同，使用回调而不是Promise
  3. 数据库迁移：手动跟踪，没有合适的迁移工具
  4. [其他重大债务]

变通方法和陷阱

  • 环境变量：即使对于预发环境，也必须设置 NODE_ENV=production（历史原因）
  • 数据库连接：连接池硬编码为10，更改会破坏支付服务
  • [开发人员需要知道的其他变通方法]

集成点和外部依赖

外部服务

服务 目的 集成类型 关键文件
Stripe 支付 REST API src/integrations/stripe/
SendGrid 电子邮件 SDK src/services/emailService.js

等等...

内部集成点

  • 前端通信：端口3000上的REST API，需要特定的头信息
  • 后台作业：Redis队列，参见 src/workers/
  • [其他集成]

开发和部署

本地开发设置

  1. 实际可行的步骤（不是理想步骤）
  2. 设置的已知问题
  3. 所需的环境变量（参见 .env.example）

构建和部署过程

  • 构建命令：npm run build（webpack配置在 webpack.config.js 中）
  • 部署：通过 scripts/deploy.sh 手动部署
  • 环境：开发、预发、生产（参见 config/environments/）

测试现状

当前测试覆盖率

  • 单元测试：60%覆盖率（Jest）
  • 集成测试：最少，在 tests/integration/ 中
  • 端到端测试：无
  • 手动测试：主要的QA方法

运行测试

npm test           # 运行单元测试
npm run test:integration  # 运行集成测试（需要本地数据库）

如果提供了增强PRD - 影响分析

需要修改的文件

根据增强需求，这些文件将受到影响：

  • src/services/userService.js - 添加新的用户字段
  • src/models/User.js - 更新模式
  • src/routes/userRoutes.js - 新的端点
  • [等等...]

需要的新文件/模块

  • src/services/newFeatureService.js - 新的业务逻辑
  • src/models/NewFeature.js - 新的数据模型
  • [等等...]

集成注意事项

  • 需要与现有的身份验证中间件集成
  • 必须遵循 src/utils/responseFormatter.js 中的现有响应格式
  • [其他集成点]

附录 - 有用的命令和脚本

常用命令

npm run dev         # 启动开发服务器
npm run build       # 生产构建
npm run migrate     # 运行数据库迁移
npm run seed        # 填充测试数据

调试和故障排除

  • 日志：检查 logs/app.log 以获取应用程序日志
  • 调试模式：设置 DEBUG=app:* 以获取详细日志
  • 常见问题：参见 docs/troubleshooting.md]]

4. 文档交付

  1. 在Web UI中（Gemini, ChatGPT, Claude）：

    • 在一个响应中呈现整个文档（如果太长则分多个）
    • 告诉用户复制并另存为 docs/brownfield-architecture.md 或 docs/project-architecture.md
    • 如果需要，提及以后可以在IDE中分片

  2. 在IDE环境中：

    • 将文档创建为 docs/brownfield-architecture.md
    • 告知用户此单个文档包含所有架构信息
    • 如果需要，以后可以使用PO代理分片

文档应足够全面，以便将来的代理能够理解：

  • 系统的实际状态（非理想化）
  • 在哪里找到关键文件和逻辑
  • 存在哪些技术债务
  • 必须遵守哪些约束
  • 如果提供了PRD：增强功能需要更改什么]]

5. 质量保证

关键：在最终确定文档之前：

  1. 准确性检查：验证所有技术细节与实际代码库匹配
  2. 完整性审查：确保所有主要系统组件都已记录
  3. 重点验证：如果用户提供了范围，验证相关领域是否被强调
  4. 清晰度评估：检查解释对AI代理是否清晰
  5. 导航：确保文档具有清晰的章节结构，便于参考

在主要章节后应用高级启发任务，以根据用户反馈进行完善。

成功标准

  • 创建了单一的综合性棕地架构文档
  • 文档反映了现实，包括技术债务和变通方法
  • 关键文件和模块用实际路径引用
  • 模型/API引用源文件而不是重复内容
  • 如果提供了PRD：清晰的影响分析，显示需要更改的内容
  • 文档使AI代理能够导航和理解实际代码库
  • 清楚地记录了技术约束和“陷阱”

说明

  • 此任务创建一个捕获系统真实状态的单一文档
  • 尽可能引用实际文件而不是重复内容
  • 诚实地记录技术债务、变通方法和约束
  • 对于有PRD的棕地项目：提供清晰的增强影响分析
  • 目标是为从事实际工作的AI代理提供实用的文档