1. 项目概述：为AI智能体装上“项目经理”大脑

如果你正在使用Claude Code、Cursor这类AI编程助手，或者任何支持Agent Skills标准的智能体平台，你肯定遇到过这样的场景：昨天和AI讨论得热火朝天的项目细节，今天打开新会话时，它已经忘得一干二净；想同时推进多个功能模块，却发现AI只能串行处理，效率低下；好不容易写好的需求文档，AI在编码时却自行其是，最终交付物与预期相差甚远。这种“上下文蒸发”、“单线程阻塞”和“随意编码”的问题，正是传统AI辅助开发流程的痛点。

CCPM（The 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，其安装过程非常简洁。首先，确保你的系统满足两个核心前提条件：

1. Git ：版本控制的基础。
2. 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，我需要了解几个关键点：

1. 核心用户是谁？（例如：博客读者、内容创作者、审核管理员）
2. 成功上线的关键指标是什么？（例如：评论提交成功率 > 99.9%，加载时间 < 1秒）
3. 有哪些必须遵守的技术约束？（例如：必须与现有的用户系统集成，使用MySQL数据库）
4. 哪些功能明确不在第一版范围内？（例如：不包含实时推送、不包含评论举报后的自动处理）
5. 评论的审核流程是怎样的？是即发即显，还是需要人工审核？”

在你逐一回答后，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会执行一系列原子操作：

1. 在你的GitHub仓库创建一个父Issue（Epic），标题为“Epic: Implement Article Comment System”。
2. 为每个任务文件创建一个子Issue，并建立父子链接（需要 gh-sub-issue 扩展，CCPM会提示你安装）。
3. 将本地的任务文件重命名，例如 001.md -> 1234.md （假设其在GitHub上对应的Issue ID是1234）。
4. 在项目目录外（如 ../epic-article-comment-system/ ）为该史诗创建一个独立的工作树。
5. 生成一个映射文件，记录本地文件与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交互的基础，必须首先解决。 排查步骤 ：

1. 运行 gh auth status ，检查当前登录状态和账号。
2. 如果未登录，运行 gh auth login ，按照提示选择HTTPS或SSH方式登录。对于大多数CI/CD环境或希望避免交互的场景，可以使用 gh auth login --with-token < your_token ，其中 your_token 是具备repo权限的GitHub Personal Access Token。
3. 确保你的Token或登录账号对目标仓库有读写权限（Issues和Contents权限是必须的）。

问题2：同步到GitHub时失败，提示关于子Issue的错误。 原因与解决 ：CCPM默认尝试使用 gh sub-issue 扩展来创建有父子关系的Issue，以获得更好的可视化。如果未安装，它会回退到普通Issue并在描述中手动标记关系。

• 最佳实践 ：安装该扩展以获得最佳体验： gh extension install yahsan2/gh-sub-issue 。
• 临时方案 ：如果安装扩展失败，CCPM的回退机制可以保证基本功能，只是GitHub界面上的父子关系不那么直观。

5.2 工作流执行问题

问题3：AI智能体似乎没有使用CCPM技能，还是在进行“感觉式编码”。 排查步骤 ：

1. 检查技能链接 ：确认CCPM技能目录已正确符号链接到你的智能体平台技能路径。对于Claude Code，检查项目根目录下的 .claude/skills/ccpm 是否存在且指向正确位置。
2. 检查触发意图 ：CCPM通过自然语言意图触发。确保你的指令清晰，例如使用“我想构建...”、“让我们规划...”、“为...创建PRD”等开头。直接说“写一个登录函数”可能不会触发完整的PM流程。
3. 查看项目结构 ：检查项目根目录下是否生成了 .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”脚本报告的信息不准确或过时。 排查步骤 ：

1. 检查文件状态 ：CCPM的脚本通过解析 .claude/epics/*/*.md 文件中的Frontmatter（特别是任务进度注释）和Git日志来工作。确保任务文件中的进度标记（如 progress: 60% ）已更新。
2. 检查Git提交 ：脚本也会查找包含“Issue #N”的提交信息。确保AI智能体在提交时使用了规范的提交信息格式。
3. 运行脚本调试 ：你可以直接运行底层的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在分解任务时保持清晰的思路。对于极其复杂的依赖，考虑将其拆分为多个更小、更独立的史诗来管理。