claude-apprentice 1.0.0

package/templates/skills/fullstack-workflow.md

@@ -0,0 +1,121 @@
+---
+name: fullstack-workflow
+description: 当需要开发完整功能模块（从数据库到前端页面）或进行前后端联调时使用
+context: fork
+---
+
+# 全栈开发流程编排器
+
+你处于全栈协调模式。本技能是完整的开发流程编排器，每个步骤关联 Superpowers Skill，根据项目配置决定是否启用。
+
+## 配置读取（流程开始前执行）
+
+读取 `.claude/memory/superpowers-config.md` 中的配置，确定每个 Skill 的启用状态：
+- **enabled** 中的 Skill → 对应步骤始终执行
+- **disabled** 中的 Skill → 对应步骤始终跳过
+- **conditional** 中的 Skill → 根据当前任务复杂度判断
+
+复杂度判断标准：
+- **简单**：单文件修改、字段调整、bug 修复（< 30 分钟）
+- **中等**：新组件 + 新接口、多文件变更（30 分钟 - 2 小时）
+- **复杂**：新功能模块、跨前后端、多表多接口（> 2 小时）
+
+---
+
+## 流程步骤
+
+### 步骤 0：需求入口 [必选]
+
+- 接收用户需求描述
+- 判断复杂度等级（简单 / 中等 / 复杂）
+- **简单任务** → 跳到步骤 4 直接实现
+- **中等任务** → 进入步骤 1
+- **复杂任务** → 进入步骤 1
+
+> 关联 Superpowers: using-superpowers（入口判断）
+
+### 步骤 1：需求澄清 + Spec 产出 [中等+复杂]
+
+- 确认功能边界：涉及哪些数据表、接口数量、页面数量
+- 向用户确认不明确的细节（鉴权方式、数据量级、异常策略等）
+- 提出方案选项，让用户选择
+- **产出：在 `specs/active/` 下创建 spec 文件**（状态 Proposed）
+- 让用户确认 spec 后，状态改为 Applied
+
+> Spec 格式参见 `.claude/specs/SPEC-GUIDE.md`
+> 关联 Superpowers: brainstorming
+> 配置项: 如 brainstorming 已禁用，直接用用户描述创建 spec
+
+### 步骤 2：任务拆解与计划 [复杂]
+
+- 将需求拆解为 2-5 分钟可完成的小任务
+- 每个任务标注：涉及文件路径、变更范围、依赖关系
+- 计划写给"一个技术很强但对项目一无所知的陌生人"看，必须精确到文件和行号
+- 输出计划让用户确认
+
+> 关联 Superpowers: writing-plans
+> 配置项: 如 writing-plans 已禁用，跳过此步骤
+
+### 步骤 3：工作空间隔离 [复杂]
+
+- 创建 git worktree 隔离开发环境
+- 在隔离环境中安装依赖、运行基线测试
+
+> 关联 Superpowers: using-git-worktrees
+> 配置项: 如 using-git-worktrees 已禁用，在当前分支直接开发
+
+### 步骤 4：实现 [必选]
+
+- 读取 `specs/active/` 中对应的 spec 文件作为约束
+
+#### 4a. 接口契约设计
+
+- 定义 API 路径、请求参数 JSON、响应 JSON 格式
+- 定义错误码和错误响应
+- 确保前后端字段名/类型一致
+
+#### 4b. 自底向上实现
+
+1. **数据库层** → 2. **DAO/Mapper 层** → 3. **Service 层** → 4. **Controller 层** → 5. **前端 API 模块** → 6. **前端页面**
+
+### 步骤 5：联调验证 [必选]
+
+- 运行后端构建和测试，贴出结果
+- 运行前端 lint 和测试，贴出结果
+- 验证前后端字段名/类型完全一致
+- **将 spec 从 `active/` 移入 `archived/`**
+
+> 关联 Superpowers: verification-before-completion
+
+### 步骤 6：代码审查 [中等+复杂，可选]
+
+- 对变更代码进行系统审查
+- 按严重度分级：Critical（必须修）、Important（应该修）、Minor（记录）
+- 逐条验证审查意见：合理的修复，不合理的说明原因（技术正确性 > 社交舒适度）
+
+> 关联 Superpowers: requesting-code-review + receiving-code-review
+> 配置项: 如 code-review 已禁用，跳过此步骤
+
+### 步骤 7：收尾 [必选]
+
+- 更新知识库（如有架构变更更新 architecture.md，有新规范更新 *-standards.md）
+- 决定分支合并策略（创建 PR / 直接合并）
+- 如使用了 worktree，清理工作空间
+
+> 关联 Superpowers: finishing-a-development-branch
+> 配置项: 如 finishing-a-development-branch 已禁用，只执行知识库更新
+
+---
+
+## 完成标准
+
+- 后端编译通过 + 测试通过
+- 前端 lint 无错误 + 测试通过
+- 端到端数据流通畅
+- 前后端字段名/类型完全一致
+- 错误链路完整
+- 验证结果已贴出
+
+## 参考规范
+
+阅读 `.claude/memory/` 目录下所有规范文档了解完整项目规范。

package/templates/specs/SPEC-GUIDE.md

@@ -0,0 +1,99 @@
+# Spec 规格驱动开发指南
+
+## 核心理念
+
+**规格是唯一的真相来源。** AI 每次从 spec 文件读约束，不靠聊天记录。
+
+## 目录结构
+
+```
+specs/
+├── SPEC-GUIDE.md          # 本指南
+├── active/                # 进行中的 spec（当前任务约束）
+│   └── [feature-name].md  # 每个功能一个文件
+└── archived/              # 已完成的 spec（历史记录）
+    └── [feature-name].md  # 归档后只读，不修改
+```
+
+## 生命周期
+
+```
+Propose（提案）→ Apply（实施）→ Archive（归档）
+```
+
+### Propose：生成规格草案
+
+触发条件：中等+复杂任务进入 workflow 步骤 1（需求澄清）时。
+
+产出：在 `specs/active/` 下创建 spec 文件，包含：
+
+```markdown
+# [功能名称] 规格
+
+## 状态
+Proposed | Applied | Completed
+
+## 需求概述
+[一句话描述做什么]
+
+## 涉及文件
+- 新增：[文件路径列表]
+- 修改：[文件路径列表]
+
+## 接口定义（如涉及 API）
+- 路径、方法、请求参数、响应格式
+
+## 数据模型变更（如涉及数据库）
+- 表名、字段、索引
+
+## 约束条件
+- [硬性约束列表]
+
+## 验收标准
+- [ ] 标准 1
+- [ ] 标准 2
+
+## 变更记录
+| 日期 | 变更内容 |
+|------|---------|
+| YYYY-MM-DD | 初始提案 |
+```
+
+### Apply：锁定规格，开始实施
+
+- 用户确认 spec 后，状态改为 `Applied`
+- 后续所有 AI Session 从这个文件读约束
+- 实施过程中的设计变更必须同步更新 spec 的变更记录
+
+### Archive：归档完成
+
+- 任务完成 + 验证通过后，状态改为 `Completed`
+- 将 spec 从 `active/` 移到 `archived/`
+- 归档的 spec 作为活文档，新人可以快速理解决策背景
+
+## Delta Spec 原则
+
+不重写整个文档，只记录增量变更。每次修改追加到"变更记录"表。
+
+## 何时写 Spec
+
+| 复杂度 | 是否写 Spec | 说明 |
+|--------|------------|------|
+| 简单 | 否 | 直接做 |
+| 中等 | 是 | 写简要 spec，确认后实施 |
+| 复杂 | 是 | 写完整 spec，含接口定义和数据模型 |
+
+## Spec 与 Workflow 的关系
+
+```
+workflow 步骤 1（需求澄清）
+  → 产出 specs/active/[feature].md（Propose）
+  → 用户确认
+
+workflow 步骤 3+（实施）
+  → 读取 spec 文件作为约束
+  → 设计变更同步更新 spec
+
+workflow 步骤 5（验证/收尾）
+  → spec 移入 specs/archived/（Archive）
+```

package/templates/specs/active/README.md

@@ -0,0 +1,7 @@
+# Active Specs
+
+进行中的功能规格文档。每个功能一个 `.md` 文件。
+
+命名规范：`[feature-name].md`，使用 kebab-case（如 `user-points-system.md`）。
+
+详见 [SPEC-GUIDE.md](../SPEC-GUIDE.md)。

package/templates/specs/archived/README.md

@@ -0,0 +1,10 @@
+# Archived Specs
+
+已完成的功能规格文档。归档后只读，不修改。
+
+保留这些文档的价值：
+- 新人快速理解决策背景
+- Delta Spec 的历史变更追溯
+- 防止重复设计
+
+详见 [SPEC-GUIDE.md](../SPEC-GUIDE.md)。

package/templates/usage-guides/README.md

@@ -0,0 +1,84 @@
+# AI 驱动全栈开发 — 使用手册版本索引
+
+## 版本列表
+
+| 版本 | 文件 | 日期 | 主要变更 |
+|------|------|------|---------|
+| v5.8 | [usage-guide-v5.8.md](usage-guide-v5.8.md) | 2026-06-22 | 瓶颈定位指南、Loop 层试点（`/scan-todos`、`auto-review.sh`）、Rules 触发索引、错误驱动闭环 |
+| v5.7 | [usage-guide-v5.7.md](usage-guide-v5.7.md) | 2026-06-02 | 评审增强；新增 `/spec` 命令（强制产出 spec，不进入实现）；FAQ 新增 Q8/Q9 |
+| v5.6 | [usage-guide-v5.6.md](usage-guide-v5.6.md) | 2026-06-01 | 章节重组：初始化提到第一节、5分钟上手加入初始化引导、代码评审前置 |
+| v5.5 | [usage-guide-v5.5.md](usage-guide-v5.5.md) | 2026-06-01 | 代码评审增强：多选提交、MD/Excel 双格式输出、reports 目录 |
+| v5.4 | [usage-guide-v5.4.md](usage-guide-v5.4.md) | 2026-06-01 | 代码评审流程重构：开放只读 git 命令、settings.json 预授权 |
+| v5.3 | [usage-guide-v5.3.md](usage-guide-v5.3.md) | 2026-05-29 | 多项目工作区、技术栈专属 rules、深度检测自动填充、增量更新模式 |
+| v5.2 | [usage-guide-v5.2.md](usage-guide-v5.2.md) | 2026-05-28 | 新增健康巡检、错误驱动学习机制、init.sh v5 兼容 |
+| v5.1 | [usage-guide-v5.1.md](usage-guide-v5.1.md) | 2026-05-27 | 原生优先理念、Spec 驱动、四层配置、CLAUDE.md 精简 |
+| v4 | [usage-guide-v4.md](usage-guide-v4.md) | 2026-05-18 | 初版完整体系：workflow、rules、skills、知识库 |
+
+## 版本演进
+
+### v4 → v5.1
+
+- CLAUDE.md 从 108 行精简到 53 行（目录式）
+- Rules 从 4 个合并为 3 个
+- 新增 Spec 机制（Propose → Apply → Archive）
+- 确立"原生优先"核心原则
+- Superpowers 配置从 CLAUDE.md 移到 memory/
+
+### v5.1 → v5.2
+
+- 新增第十三节"健康巡检"（health-check.sh 7 项自动检查）
+- 第十一节"错误驱动学习"扩充为完整机制（7 条初始教训）
+- init.sh 更新为 v5 格式（生成 learned-lessons.md、superpowers-config.md）
+- 修复 verify.sh 知识库检查拼写错误
+
+### v5.7 → v5.8
+
+- 新增瓶颈定位指南 `.claude/usage-guides/bottleneck-navigation.md`(Prompt/Context/Harness/Loop 四层模型 + 排查顺序)
+- 第二节演进线从三条扩成四条,加入 Loop Engineering
+- 新增 `/scan-todos` slash command(Loop 层首个试点,扫描 TODO/FIXME 产出报告)
+- 新增 `.claude/scripts/auto-review.sh`(commit 后异步自动 review,可独立调用或配 hook)
+- 新增 `.claude/rules/INDEX.md`(Rules 触发条件索引,让规则可审计)
+- 第十二节错误驱动学习加"加 rule 前先定位瓶颈"闭环
+- FAQ 新增 Q10:效果不好怎么排查
+- CLAUDE.md 复杂度分级表加 Prompt/Context/Harness/Loop 四列
+
+### v5.6 → v5.7
+
+- 代码评审新增维度七：文件类型专属检查（Java/Python/Go/Vue/React/SQL/XML/配置文件各一套检查项）
+- 代码评审步骤 3 增加跨文件关联分析（接口→调用方、表结构→DAO、组件→引用方）
+- 新增流程定义文件 workflow/WORKFLOW-GUIDE.md（后端/前端/全栈标准流程、阶段产物、通用规则）
+- verify.sh 新增 --baseline save/diff 基线对比功能（防止 AI 推卸责任）
+- init.sh 新增 generate_workflow() 函数
+- health-check.sh 新增第 9 项流程定义检查
+
+### v5.5 → v5.6
+
+- 章节结构重组：初始化新项目从第十二节提到第一节，5 分钟上手加入初始化引导
+- 代码评审从第九节提前到第六节（日常使用之后）
+- 新章节顺序：快速上手 → 初始化 → 哲学 → 核心理念 → 架构 → 日常使用 → 代码评审 → Spec → 工作流 → 规则 → Superpowers → 案例 → 错误学习 → 巡检 → 知识库 → FAQ → 选型 → 文件清单
+
+### v5.4 → v5.5
+
+- 代码评审支持多选提交，多个提交的变更文件自动去重合并统一评审
+- 评审报告支持 MD 和 Excel 双格式输出，用户选择后生成文件到 `.claude/reports/`
+- Excel 报告含 3 个 Sheet（评审汇总、问题清单、评审信息），问题等级按颜色区分
+- 新增 `.claude/reports/` 输出目录
+- 第九节全面重写：评审流程、输出格式、问题等级、结论判定独立为小节
+
+### v5.3 → v5.4
+
+- 代码评审流程重构：开放只读 git 命令（git show/diff/log/diff-tree）用于评审上下文获取
+- settings.json 预授权只读 git 命令，评审时不再弹出权限确认
+- 评审过程禁止所有写操作的 git 命令（commit/push/checkout/reset/merge 等）
+- 支持选择最近一次提交或从最近 10 次提交中选择
+- SKILL.md 步骤 2 更新：明确列出允许的只读 git 命令清单
+
+### v5.2 → v5.3
+
+- init.sh 新增多项目工作区支持（--workspace / --project / --scan / 自动检测）
+- 新增两层 .claude/ 结构：工作区全局共享 + 子项目技术栈专属
+- 新增 5 种技术栈专属 rules（Java/Spring Boot、Python/FastAPI、Vue、React、Go）
+- 第三节新增"单项目 vs 多项目工作区"架构说明
+- 第十二节全面重写为多项目初始化指南
+- 第十五节新增 Q5 多项目工作区问答
+- 第十七节拆分为单项目和工作区两种文件清单

package/templates/usage-guides/bottleneck-navigation.md

@@ -0,0 +1,146 @@
+# 瓶颈定位指南
+
+> AI 效果不好时,先判断瓶颈在哪一层,不要一上来就加 rule。
+
+## 四层瓶颈模型
+
+源自业界共识:每当模型变强,系统瓶颈就往外移一层。从模型的输入往外,依次是:
+
+| 层次 | 瓶颈在哪 | 解决什么 | 我们体系的对应物 |
+|------|---------|---------|----------------|
+| **Prompt** | 你怎么说 | 意图表达 | `rules/*.md` 自动注入约束 + CLAUDE.md |
+| **Context** | 你给什么 | 信息供给 | `memory/` + `specs/` + 复杂度分级控制喂量 |
+| **Harness** | 模型外的环境 | 工程化纠错 | `scripts/` 验证 + workflow 强制 + `learned-lessons.md` 闭环 |
+| **Loop** | 你本人 | 自动驱动循环 | `/loop` skill + `commands/scan-todos.md`(试点) |
+
+四层是**层层包含**关系:Prompt ⊂ Context ⊂ Harness ⊂ Loop。不是替代,是叠加。
+
+公式:`Agent = 模型 + Harness`。模型决定上限,Harness 决定落地。
+
+## 排查顺序(从内到外)
+
+效果不好时,按这个顺序排查,不要跳步:
+
+### Step 1: Prompt 层 — 意图是否清楚?
+
+**症状:** AI 完全跑偏,做的事跟你想的不是一件事
+
+**自查:**
+- 任务描述有没有明确"做什么 + 改哪里 + 输出什么"
+- 约束(边界、格式、保留什么)说清楚了吗
+- 同一件事换个说法会不会效果更好
+
+**修复方向:** 改 prompt,或在 `rules/` 加更明确的约束
+
+### Step 2: Context 层 — 信息是否齐全?
+
+**症状:** AI 理解任务,但做出来跟项目其他地方冲突,或重复造轮子
+
+**自查:**
+- 相关的 spec 文档给到了吗
+- memory 里的架构、规范引用了吗
+- 上下文是不是太长导致 context rot(超过 40% 后质量下降)
+
+**修复方向:**
+- 信息不够 → 补 spec、引用 memory
+- 信息太杂 → 拆任务、主动开新对话
+
+### Step 3: Harness 层 — 环境是否防错?
+
+**症状:** AI 老犯同样的错,每次都得手动纠正
+
+**自查:**
+- 这个错以前犯过吗(查 `learned-lessons.md`)
+- 有对应的 rule 吗?rule 触发了吗
+- 验证脚本能不能拦住
+
+**修复方向:**
+- 犯过但没记 → 写进 `learned-lessons.md`
+- 记了但没 rule → 加 rule 到 `rules/`
+- 有 rule 但没拦住 → 考虑迁移到 `settings.json` hooks(确定性拦截)
+
+### Step 4: Loop 层 — 是不是该自动化?
+
+**症状:** 同一类任务反复手动驱动,耗时费力
+
+**自查:**
+- 这个任务有固定模式吗
+- 能不能让 AI 自己定时跑
+- 输入输出能不能标准化
+
+**修复方向:**
+- 写成 slash command(如 `commands/scan-todos.md`)
+- 用 `/loop` skill 配定时
+- 配 hook 自动触发
+
+## 常见误判
+
+| 误判 | 实际情况 |
+|------|---------|
+| "AI 太笨了" | 多数是 Context 没给够,不是模型问题 |
+| "加条 rule 就好了" | Rule 是 Harness 层,如果瓶颈在 Context,加 rule 没用 |
+| "这个任务做不了" | 可能只是没拆细,每个子任务在干净上下文里做 |
+| "这套体系没用" | 多数是用了错的层 — 简单任务用了完整 workflow,复杂任务只用了原生 |
+
+## 真实排查案例
+
+以下三个案例分别对应 Prompt / Context / Harness 三层,全部来自本体系的真实场景。
+
+### 案例 1:Prompt 层 — 同件事换个说法,效果差 10 倍
+
+**现象:** 让 AI"加搜索功能",它给网页加了搜索框;但实际需求是给 API 加搜索参数
+
+**误判:** 以为模型理解能力差,反复强调"按需求做"
+
+**实际瓶颈:** Prompt — 任务描述模糊,"搜索功能"有歧义(可指 UI,也可指 API)
+
+**修复:** 改成"给 `/api/users` 加 `keyword` 参数,支持按姓名/邮箱模糊搜索,返回分页结果" → AI 一次就做对
+
+**教训:** Prompt 没说清之前,别急着上更重的工具。先问自己:换个说法会不会更好?
+
+---
+
+### 案例 2:Context 层 — CLAUDE.md 膨胀让 AI "不守规矩"
+
+**现象:** AI 有时守规矩有时不守,行为不稳定。同一个项目,同一个任务,每次结果不一样
+
+**误判:** 以为规则不够严,不断往 CLAUDE.md 加更多约束(53 → 108 行),结果**更糟**
+
+**实际瓶颈:** Context — 文件太长导致 context rot,AI 在大量规则中抓不住重点,反而忽略关键约束
+
+**修复:** 精简 CLAUDE.md(108 → 53 行,目录式),详细内容移到 `rules/` 和 `memory/` 按需加载。AI 行为立刻稳定
+
+**教训:** "AI 不守规矩"多数是 Context 没给准(给得太多反而抓不住),不是规则不够严。**加 rule 前,先想想是不是该删 rule。**
+
+---
+
+### 案例 3:Harness 层 — `/scan-todos` 自指噪声
+
+**现象:** 跑 `/scan-todos` 扫到 12 条匹配,全是命令文档自身的 `TODO`/`FIXME` 字样,真实待办 = 0
+
+**误判:** 一度以为项目代码太干净,或扫描范围错了
+
+**实际瓶颈:** Harness — 命令设计有缺陷,没排除命令文档所在目录(`.claude/commands/`、`.claude/usage-guides/`),扫描器扫到了自己头上
+
+**修复(三步闭环):**
+1. **沉淀 lesson** — 在 `learned-lessons.md` 新建"Loop 层错误"分类,加 L-008
+2. **改进环境** — `scan-todos.md` 升级到 v2:排除目录 + 自指过滤规则 + 情况 A/B 双模板
+3. **同步索引** — `usage-guide-v5.8.md` 11.1 表格加 L-008 行
+
+**教训:** Loop 层试点跑一次就暴露工程问题 — 这正是 Loop 的价值,不是失败。跑试点踩坑 → 沉淀 lesson → 改进环境,这就是 Mitchell Hashimoto 的复利思维。**这种坑只发生一次,下次结构上就不可能再犯。**
+
+---
+
+## 复杂度分级 × 四层对照
+
+| 级别 | Prompt | Context | Harness | Loop |
+|------|--------|---------|---------|------|
+| 简单 | ✅ 基础描述 | ✅ 当前文件 | ⚙️ rules 自动触发 | ❌ 不需要 |
+| 中等 | ✅ 完整描述 | ✅ + 相关 spec + memory | ⚙️ + 验证脚本 + learned-lessons | ❌ 通常不需要 |
+| 复杂 | ✅ 完整描述 | ✅ + 全量 spec | ⚙️ + 完整 workflow + worktree | ✅ 探索试点 |
+
+## 参考
+
+- [Prompt/Context/Harness/Loop 原文](https://mp.weixin.qq.com/s/eeB14yOtDU6akQUp0Mkauw)
+- `.claude/memory/learned-lessons.md` — 错误登记册
+- `.claude/rules/INDEX.md` — Rules 触发条件索引