1. 项目概述为AI智能体装上“项目经理”大脑如果你正在使用Claude Code、Cursor这类AI编程助手或者任何支持Agent Skills标准的智能体平台你肯定遇到过这样的场景昨天和AI讨论得热火朝天的项目细节今天打开新会话时它已经忘得一干二净想同时推进多个功能模块却发现AI只能串行处理效率低下好不容易写好的需求文档AI在编码时却自行其是最终交付物与预期相差甚远。这种“上下文蒸发”、“单线程阻塞”和“随意编码”的问题正是传统AI辅助开发流程的痛点。CCPMThe Project Manager Agent正是为了解决这些问题而生。它不是一个独立的应用而是一个遵循Agent Skills开放标准的“技能包”你可以把它理解为给AI智能体安装的一个“项目经理”大脑。这个大脑的核心工作方式是强制推行一套基于规格驱动的开发流程将模糊的想法转化为结构化的产品需求文档PRD再将PRD拆解为技术史诗Epic和具体任务Task最后通过GitHub Issues和工作树Worktree实现多智能体并行执行。整个过程就像在软件开发中引入了严格的敏捷项目管理方法论只不过项目经理和执行者都是AI。这套系统的价值在于它将项目状态从易失的聊天记录中解放出来固化到项目仓库的文件系统里。无论是PRD、技术方案还是任务分解都以Markdown文件的形式存储在.claude/目录下成为项目的单一事实来源。这意味着你可以随时中断工作几天后再回来AI依然能基于这些文件快速恢复上下文继续推进。更重要的是它通过分析任务间的依赖关系能够智能地启动多个AI智能体同时处理不同的工作流将传统的串行开发模式转变为真正的并行工程。2. 核心设计理念告别“感觉式编码”2.1 什么是“Vibe Coding”及其危害在深入CCPM的具体实现前我们需要先理解它要对抗的核心问题“Vibe Coding”我习惯称之为“感觉式编码”。这指的是AI甚至包括一些开发者在没有明确、书面规格的情况下仅凭对话中的只言片语或模糊记忆进行开发。比如你告诉AI“我们需要一个用户登录功能”它可能直接开始编写JWT令牌的逻辑而你心里想的是OAuth 2.0第三方登录。由于缺乏成文的、可供反复查阅的规格说明这种开发方式必然导致需求漂移、上下文丢失和最终的返工。CCPM的设计哲学非常明确每一行代码都必须能追溯到一个明确的规格说明。这听起来有些严苛甚至像瀑布模型的回归但实际上它借鉴了敏捷和极限编程中“编写可执行的规格说明”的思想只不过执行者从人变成了AI。通过强制性的五阶段纪律CCPM确保了从想法到代码的路径是可预测、可审计的。2.2 五阶段开发纪律详解CCPM将整个开发流程固化为五个不可跳跃的阶段每个阶段都有明确的产出物和验收标准第一阶段深度构思Brainstorm这个阶段的目标不是立即产出文档而是进行比通常更深入的思考。CCPM会引导你或你的AI回答一系列结构化问题这个功能要解决的核心问题是什么目标用户是谁成功上线的衡量标准是什么有哪些技术或业务上的约束条件哪些内容明确不在本次范围之内这个阶段的输出是一份结构化的PRD草案它确保了所有利益相关者包括未来的AI执行者对“做什么”和“为什么做”达成共识。第二阶段规格文档化Document基于构思阶段的输出CCPM会生成一份正式的PRD文档。这份文档的关键在于“消除一切歧义”。它不会使用“快速的”、“用户友好的”这类模糊词汇而是会定义具体的指标例如“API响应时间P95小于200毫秒”、“新用户注册流程步骤不超过3步”。文档会存储在.claude/prds/目录下成为后续所有工作的基石。第三阶段技术规划Plan这是将产品需求转化为技术方案的关键一步。CCPM会“解析”PRD生成一个技术史诗Epic文件。这个文件会做出明确的技术决策选择什么数据库采用什么架构模式如MVC、Clean Architecture定义哪些API接口它会预估出大致的任务类别为下一步的分解做好准备。这个文件是开发者的技术蓝图避免了AI在编码时做出未经讨论的架构选择。第四阶段精准执行Execute在此阶段CCPM会将技术史诗分解为具体的、可执行的任务。每个任务文件都包含清晰的验收标准、工作量估算以及最重要的元数据depends_on依赖哪些任务、parallel是否可以并行执行和conflicts_with与哪些任务冲突。这些元数据是后续实现并行执行的“调度依据”。第五阶段透明追踪Track项目状态不再隐藏在聊天历史中。CCPM提供了一系列通过Bash脚本实现的确定性操作如standup每日站会报告、status整体状态、next下一步任务、blocked阻塞项。这些脚本直接扫描项目文件瞬间给出结果无需消耗LLM的Token保证了信息的实时性和准确性。3. 核心机制解析如何实现并行与上下文持久化3.1 基于GitHub Issues的单一事实来源CCPM选择GitHub Issues作为协同工作的核心这是一个极具巧思的设计。大多数AI编码工具都运行在孤立的会话中状态无法共享。而GitHub Issues是一个天然的、被广泛接受的“工作项”数据库。CCPM利用它实现了几个关键能力真正的团队协作多个AI智能体甚至可以混合人类开发者可以同时在同一个项目上工作。一个智能体在处理身份验证逻辑另一个在编写前端组件它们的进度通过Issue的评论和状态变更实时可见互不干扰。无缝的工作交接AI可以开始一个任务人类开发者可以中途介入完成它或者反之。所有讨论和决策都记录在Issue的评论线程中避免了“AI之前到底做了什么”的沟通会议。零额外基础设施你不需要维护另一个项目管理数据库如Jira、Trello。项目的状态就是Issue的状态评论记录就是审计日志。它还能与你现有的GitHub标签、里程碑和PR工作流无缝集成。在实际操作中当你运行sync命令时CCPM会在你的GitHub仓库中创建一个“史诗级”的父Issue然后将每个分解后的任务作为子Issue链接到父Issue之下。本地任务文件如001.md会被重命名为对应的GitHub Issue ID如1234.md建立起一一对应的映射关系。3.2 工作树并行执行的隔离沙箱并行执行的最大挑战是代码冲突。如果多个AI智能体同时向主工作区的同一个文件提交代码必然导致混乱。CCPM的解决方案是使用Git的工作树功能。当你为一个史诗Epic执行sync操作时CCPM不仅会在GitHub上创建Issues还会在项目目录的同级位置创建一个独立的工作树目录例如../epic-notification-system/。这个目录是一个完整的、独立的Git工作区但它指向同一个Git仓库。这样每个并行的工作流Stream都可以被分配到这个独立的工作树中进行开发。智能体A在工作树中修改auth.service.js智能体B在另一个工作树或主工作区修改user.model.js它们之间的操作在物理上是隔离的。完成各自的任务后它们通过常规的Git流程commit, push, pull request将代码变更合并回主分支由Git的版本控制机制来处理可能的合并冲突。这模拟了真实团队中多个开发者基于特性分支工作的模式。3.3 任务分析与智能并行调度CCPM的“智能”体现在它对任务的解析和调度上。当你命令“开始处理Issue #42”时CCPM并不会简单地让一个AI去啃整个Issue。它会先对任务文件42.md进行“流分析”。例如一个“实现用户认证”的任务经过分析可能被拆分为三个可并行的工作流Stream A (后端逻辑)创建数据库迁移、编写用户服务层、实现密码哈希。Stream B (API层)设计RESTful端点、编写中间件、处理输入验证。Stream C (前端集成)创建登录/注册表单组件、管理用户状态、处理令牌存储。分析完成后CCPM可以同时启动多个AI智能体实例每个实例被精确地指派到其中一个工作流并给予其对应的上下文例如Stream A的智能体只关心epic.md中关于后端架构的部分和42.md中关于数据库和服务的验收标准。这种基于上下文的精准指派极大地减少了单个智能体的认知负荷避免了“无关信息干扰”提升了代码生成的质量和针对性。4. 完整工作流实操指南4.1 环境准备与技能安装CCPM作为一个Agent Skill其安装过程非常简洁。首先确保你的系统满足两个核心前提条件Git版本控制的基础。GitHub CLI (gh)并且需要完成认证gh auth login。这是CCPM与GitHub API交互的桥梁。接下来克隆CCPM仓库并链接到你的智能体平台技能目录# 1. 克隆仓库 git clone https://github.com/automazeio/ccpm.git # 2. 根据你的智能体平台进行链接 # 例如对于 Claude Code项目根目录下操作 mkdir -p .claude/skills ln -s /path/to/ccpm/skill/ccpm .claude/skills/ccpm # 对于 Factory/Droid 平台 ln -s /path/to/ccpm/skill/ccpm ~/.factory/skills/ccpm安装完成后CCPM技能会自动激活。你无需记忆任何特殊命令只需用自然语言与你的AI智能体对话即可。4.2 阶段一从想法到PRD假设我们想开发一个“文章评论系统”。与AI的对话可能如下你“我想构建一个文章评论系统支持嵌套回复和表情回复。”此时CCPM技能被触发AI不会立即开始设计数据库而是会进入引导式提问阶段AI (CCPM)“好的让我们先把这个想法具体化。为了创建清晰的PRD我需要了解几个关键点核心用户是谁例如博客读者、内容创作者、审核管理员成功上线的关键指标是什么例如评论提交成功率 99.9%加载时间 1秒有哪些必须遵守的技术约束例如必须与现有的用户系统集成使用MySQL数据库哪些功能明确不在第一版范围内例如不包含实时推送、不包含评论举报后的自动处理评论的审核流程是怎样的是即发即显还是需要人工审核”在你逐一回答后AI会在.claude/prds/article-comment-system.md生成一份结构化的PRD。这份文档会详细描述背景、目标用户、功能清单如发布评论、回复评论、添加表情、审核列表、非功能性需求性能、安全以及发布计划。4.3 阶段二从PRD到技术史诗有了PRD下一步是进行技术规划。你“解析一下 article-comment-system 这个PRD。”AI (CCPM)它会读取PRD并生成技术史诗文件.claude/epics/article-comment-system/epic.md。这个文件可能包含以下内容架构决策采用REST API还是GraphQL选择Node.js Express还是Python FastAPI数据模型设计comments表的核心字段id, content, article_id, user_id, parent_id, emoji_reactions JSON。API设计GET /api/articles/:id/comments,POST /api/comments,PUT /api/comments/:id/reaction。任务预览初步识别出“数据库设计”、“后端服务”、“API端点”、“前端组件”、“测试”等任务类别。4.4 阶段三任务分解与GitHub同步你“把 article-comment-system 这个史诗分解成任务。”CCPM会创建一系列任务文件001.md,002.md...每个文件都有类似以下的Frontmatter元数据--- title: “设计并创建评论数据表” acceptance_criteria: - “创建 comments 表的迁移文件” - “字段包含id, content, article_id, user_id, parent_id, created_at, updated_at” - “为 article_id 和 user_id 创建外键索引” - “为 parent_id 创建自关联索引以优化嵌套查询” effort: “M” # 中等工作量 depends_on: [] # 无前置依赖 parallel: true # 可并行执行 conflicts_with: [] # 无冲突任务 ---分解完成后便是与GitHub同步的时刻。你“将 article-comment-system 史诗同步到GitHub。”CCPM会执行一系列原子操作在你的GitHub仓库创建一个父IssueEpic标题为“Epic: Implement Article Comment System”。为每个任务文件创建一个子Issue并建立父子链接需要gh-sub-issue扩展CCPM会提示你安装。将本地的任务文件重命名例如001.md-1234.md假设其在GitHub上对应的Issue ID是1234。在项目目录外如../epic-article-comment-system/为该史诗创建一个独立的工作树。生成一个映射文件记录本地文件与GitHub Issue ID的对应关系。至此你的想法已经完全转化为GitHub上可跟踪、可分配的工作项。4.5 阶段四并行执行与开发现在可以开始真正的编码了。你“开始处理 issue #1235。”假设这是“创建评论API端点”的任务CCPM会分析1235.md任务文件识别出可以并行的工作流。它可能会启动两个AI智能体智能体A工作树中负责编写Express路由控制器、请求验证逻辑和Service层调用。智能体B主工作区负责编写对应的API集成测试用例如使用Supertest。两个智能体在各自的上下文中工作定期提交代码提交信息会包含“Issue #1235: [描述]”。你可以通过Git历史清晰地看到每个Issue的代码贡献。4.6 阶段五跟踪与状态管理在整个开发过程中你可以随时询问项目状态所有查询都由高效的Bash脚本处理响应是即时的。你“standup”站会终端输出 每日站会 — 2023-10-27 进行中 • Issue #1235 (创建评论API端点) — 后端逻辑完成进度 80% • Issue #1236 (评论列表查询接口) — 数据库查询优化中进度 60% ⏭️ 下一步 • Issue #1237 (前端评论组件) — 等待 #1235 的API定义 阻塞项 • Issue #1238 (表情选择器UI) — 依赖 #1237 的组件框架 汇总2项进行中3项待开始0项已完成你“what‘s blocked?”什么被阻塞了你“search 数据库索引”搜索相关内容这些命令让你对项目全局了如指掌完全摆脱了在冗长聊天记录中翻找进度的困境。5. 常见问题与实战避坑指南5.1 安装与配置问题问题1执行gh命令时提示“认证失败”或“无权限”。注意这是CCPM与GitHub交互的基础必须首先解决。排查步骤运行gh auth status检查当前登录状态和账号。如果未登录运行gh auth login按照提示选择HTTPS或SSH方式登录。对于大多数CI/CD环境或希望避免交互的场景可以使用gh auth login --with-token your_token其中your_token是具备repo权限的GitHub Personal Access Token。确保你的Token或登录账号对目标仓库有读写权限Issues和Contents权限是必须的。问题2同步到GitHub时失败提示关于子Issue的错误。原因与解决CCPM默认尝试使用gh sub-issue扩展来创建有父子关系的Issue以获得更好的可视化。如果未安装它会回退到普通Issue并在描述中手动标记关系。最佳实践安装该扩展以获得最佳体验gh extension install yahsan2/gh-sub-issue。临时方案如果安装扩展失败CCPM的回退机制可以保证基本功能只是GitHub界面上的父子关系不那么直观。5.2 工作流执行问题问题3AI智能体似乎没有使用CCPM技能还是在进行“感觉式编码”。排查步骤检查技能链接确认CCPM技能目录已正确符号链接到你的智能体平台技能路径。对于Claude Code检查项目根目录下的.claude/skills/ccpm是否存在且指向正确位置。检查触发意图CCPM通过自然语言意图触发。确保你的指令清晰例如使用“我想构建...”、“让我们规划...”、“为...创建PRD”等开头。直接说“写一个登录函数”可能不会触发完整的PM流程。查看项目结构检查项目根目录下是否生成了.claude/prds/或.claude/epics/目录。如果没有说明技能未被激活或未找到项目根目录。问题4并行执行时多个AI智能体修改了同一个文件导致合并冲突。原因与解决这通常是因为任务分解得不够“原子”或者conflicts_with元数据未正确设置。任务分解原则确保每个任务文件对应一个尽可能独立的功能单元。例如“实现用户认证”应该分解为“设计数据表”、“编写密码服务”、“创建登录API”、“创建注册API”等多个任务并为可能修改相同模型文件的任务设置conflicts_with。善用工作树CCPM创建的工作树是主要的隔离手段。确保为不同的并行工作流明确指定不同的工作目录。虽然CCPM会尝试自动分配但在复杂场景下手动干预和清晰的规划仍是避免冲突的上策。人工协调将CCPM视为一个强大的协调者但最终的代码合并决策权仍在开发者手中。定期运行git status和查看PR在冲突发生前进行人工干预和任务调整。5.3 文件与状态管理问题问题5.claude/目录下的文件混乱或者我想重置某个史诗的规划。操作指南.claude/目录是纯文本文件管理起来非常灵活。归档史诗直接将已完成或废弃的史诗目录如.claude/epics/old-feature/移动到.claude/archive/目录下需手动创建。重置规划如果你想重新规划某个功能最简单的方法是删除整个史诗目录如rm -rf .claude/epics/my-feature/然后从“我想构建...”重新开始。Git会跟踪这些文件的删除你也可以选择先提交一次以保存旧的规划记录。手动编辑所有PRD、Epic、Task文件都是Markdown格式你可以随时用文本编辑器打开并修改。修改后可以对AI说“根据我更新的文件重新规划一下任务”CCPM会读取最新内容。问题6“standup”或“status”脚本报告的信息不准确或过时。排查步骤检查文件状态CCPM的脚本通过解析.claude/epics/*/*.md文件中的Frontmatter特别是任务进度注释和Git日志来工作。确保任务文件中的进度标记如progress: 60%已更新。检查Git提交脚本也会查找包含“Issue #N”的提交信息。确保AI智能体在提交时使用了规范的提交信息格式。运行脚本调试你可以直接运行底层的Bash脚本来查看原始输出例如bash .claude/skills/ccpm/references/scripts/standup.sh。这有助于判断是脚本逻辑问题还是数据源问题。5.4 高级技巧与最佳实践技巧1混合人机协作。CCPM最大的优势之一是打通了AI与人的工作流。你可以自己动手完成一个任务在对应的GitHub Issue下评论“我来处理”然后在本地的任务文件如1234.md中更新状态最后关闭该Issue。CCPM的跟踪脚本会识别到这一变化。同样AI完成的工作你可以轻松地通过Issue进行代码审查。技巧2迭代式规划。你不必在第一天就规划出完美的、不可更改的PRD。可以采用“滚动式规划”先为一个最小可行产品MVP创建PRD并执行。在开发过程中将新发现的需求或变更记录为新的GitHub Issue并适时地将其纳入到后续的史诗规划中可以创建epic-v2.md。CCPM的文件系统让这种迭代变得非常自然。技巧3定制化脚本。CCPM自带的Bash脚本在skill/ccpm/references/scripts/都是可读、可修改的。如果你的团队有特殊的状态报告需求例如需要同步到Slack或生成燃尽图你可以复制并修改这些脚本加入自定义的逻辑。这是将CCPM适配到自身工作流的强大方式。技巧4管理复杂依赖。对于大型项目任务依赖网络可能非常复杂。除了使用depends_on和conflicts_with建议在史诗规划epic.md中绘制一个简单的依赖图。虽然CCPM不直接解析图形但这能帮助你和AI在分解任务时保持清晰的思路。对于极其复杂的依赖考虑将其拆分为多个更小、更独立的史诗来管理。