i 什么是 project-blueprint？
project-blueprint 是一套标准化开发工作流，规定所有 Claude Code 新项目必须遵循的流程、目录结构和质量门禁。它确保：
- 每个需求从第一性原理出发设计，通过奥卡姆剃刀精简
- 设计通过对抗性验证确保无遗漏、无冗余
- 实现由 Claude Code 执行，Hermes 负责编排、检查和验证
- 所有产出可追溯：设计事实 → 流程图 → 测试用例 → Bug 记录
☍ 核心设计原则
| 原则 | 含义 | 应用场景 |
|---|---|---|
| 第一性原理 | 剥离假设，回归事物本质目的，从基本约束推导方案 | 所有设计决策 |
| 奥卡姆剃刀 | 满足目的前提下选最简方案，拒绝不必要复杂度 | 方案评审、代码审查 |
| 对抗性验证 | 主动攻击方案和实现的弱点：边界值、异常输入、并发、空数据 | 门禁 1/2/3 全部使用 |
| 设计事实驱动 | 设计事实是单一真相源，流程图/时序图/页面都是它的投影 | 阶段二（方案确认） |
⬇ 完整流程图（PlantUML 生成 · 可缩放/拖拽）
0 阶段〇 · 触发
*** 开始使用 project-blueprint ***- 用户说出触发词：
新项目、启动 project-blueprint、按 blueprint 流程 - Hermes 加载
project-blueprintskill，输出标记以确认进入工作流 - 后续所有阶段必须顺序执行，不可跳过
1 阶段一 · 需求对齐
*** 阶段一：需求对齐 ***- 一次一个问题，逐步明确：真实目的 → 约束条件 → 成功标准
- 产出：一份需求陈述，双方共识
- 关键：不是「用户说了什么」，而是「用户真正需要什么」——用第一性原理剥离表面需求
2 阶段二 · 方案确认
*** 阶段二：方案确认 ***- 提出 2-3 个设计方案，含 trade-off 分析和推荐理由
- 用户确认后，写入
features/<feature>/DESIGN.md - 先写「设计事实」（单一真相源）——实体、数据流、角色、业务规则、状态转换
- 从设计事实派生图表：
- 必有：PlantUML 流程图（
flow.puml） - 条件：参与者 ≥3 且有异步交互 → PlantUML 时序图（
sequence.puml） - 条件：涉及 UI → HTML 页面 mockup（
page-mockup.html）
- 必有：PlantUML 流程图（
- 所有图表必须用 PlantUML（用户明确指定）
- 设计变更时先改设计事实，再重新派生图表——绝不直接改图
⚑ 三道强制质量门禁
门禁不通过 → 不进入下一阶段。所有门禁使用第一性原理 + 对抗性验证。
| 门禁 | 时机 | 方法 | 检查什么 |
|---|---|---|---|
| 门禁 1：设计 | 阶段二 | 第一性原理 + 剃刀原理 | 方案是否从本质目的推导？是否最简？ |
| 门禁 2：需求匹配 | 阶段二 | 第一性原理 + 对抗性验证 | 设计是否覆盖所有需求？从需求逐条导出验收用例 |
| 门禁 3：实现正确 | 阶段三 | 第一性原理 + 对抗性验证 | 实现是否与 DESIGN.md 一致？所有测试通过？Web 页面需 Playwright 验证 |
3 阶段三 · 任务实现
*** 阶段三：任务实现 ***Hermes 根据任务特征自主选择执行方式：
| 执行方式 | 适用条件 | 说明 |
|---|---|---|
| 🐝 蜂群模式 | 可拆 ≥4 低耦合 slot，汇合是文件组装 | 蜂群执行详情 ↓ |
| 👤 单 Worker | 任务紧密耦合，需要全局一致性 | Claude Code 全包实现（claude -p） |
| ✂️ 直接编辑 | ≤2 文件、<100 行改动 | 使用 patch 或 write_file |
- 所有编码工作交由 Claude Code，Hermes 不写代码
- 实现完成后运行全部测试（Playwright E2E + 单元测试）
- 涉及 Web 页面时，门禁 3 强制通过 Playwright 逐元素验证功能与样式
🐝 蜂群执行模式（swarm-execution）
*** 阶段三使用 swarm-execution 蜂群模式 ***将复杂任务拆为多个独立 slot，并行委派给 Claude Code worker，Python 脚本确定性汇合。零 LLM 中转链路。
| 阶段 | 操作 | 执行者 |
|---|---|---|
| Phase 3a · 分解 | Claude Code 分析源码，输出 task_map.json（固定 schema） | Claude Code |
| Phase 3b · 闸门 | 展示 slot 列表给用户 review，确认后 Hermes 生成 collector.py | Hermes |
| Phase 3c · 并行执行 | 拓扑排序 → 最多 3 worker 并行 → 每个 worker 只读 global_spec + 自己的 slot_spec | Claude Code ×N |
| Phase 3d+3e · 汇合与验证 | Python collector.py 检查覆盖率 → 100% 后组装 → 运行测试 | Hermes |
4 阶段四 · 复用与总结
*** 阶段四：复用与总结 ***- 汇总阶段二/三遇到的问题、踩过的坑、发现的 Bug
- 写入
features/<feature>/BUGS.md（feature 局部）+docs/bug-registry.md（全局） - 每个 Bug 修复必须追加回归测试
- 未来设计或改造模块前，先查 bug-registry 避免重蹈覆辙
📦 交付
- Web 页面：部署到 Cloudflare Pages，提供永久链接（
*.pages.dev） - 方案/报告：自包含 HTML 文件 + Cloudflare Pages 永久链接
- 代码项目：代码仓库 + 完整文档
⚡ 自动同步：此页面随
project-blueprint skill 更新而自动重新生成和部署。来源：~/.hermes/skills/software-development/project-blueprint/SKILL.md