claude-apprentice 1.0.0

package/install.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ── claude-apprentice 一键安装脚本 ────────────────────────────────────
+# 用法:
+#   curl -fsSL https://raw.githubusercontent.com/shuoyue/claude-apprentice/main/install.sh | bash
+#   curl -fsSL https://raw.githubusercontent.com/shuoyue/claude-apprentice/main/install.sh | bash -s -- v1.0.0
+# ─────────────────────────────────────────────────────────────────────
+
+VERSION="${1:-latest}"
+TARGET="$(pwd)"
+REPO_RAW="https://raw.githubusercontent.com/shuoyue/claude-apprentice"
+REPO_GIT="https://github.com/shuoyue/claude-apprentice.git"
+BRANCH="main"
+
+if [ "$VERSION" != "latest" ]; then
+  BRANCH="$VERSION"
+fi
+
+echo ""
+echo "  claude-apprentice Installer"
+echo "  版本: $VERSION"
+echo "  目标: $TARGET"
+echo ""
+
+# ── 检查依赖 ──────────────────────────────────────────────────────────
+
+command -v curl >/dev/null 2>&1 || { echo "  ✗ 需要 curl"; exit 1; }
+
+# ── 下载模板文件 ──────────────────────────────────────────────────────
+
+CLAUDE_DIR="$TARGET/.claude"
+
+echo "  下载模板文件..."
+
+# 方法: 用 git clone（如果可用）或 curl 逐个下载
+if command -v git >/dev/null 2>&1; then
+  TMP_DIR=$(mktemp -d)
+  git clone --depth 1 --branch "$BRANCH" \
+    "$REPO_GIT" "$TMP_DIR" 2>/dev/null || {
+    echo "  ✗ 克隆失败，请检查仓库地址和版本号"
+    rm -rf "$TMP_DIR"
+    exit 1
+  }
+
+  # 复制 templates/ 到 .claude/（已有文件不覆盖）
+  if [ -d "$TMP_DIR/templates" ]; then
+    mkdir -p "$CLAUDE_DIR"
+    # 用 cp -n（不覆盖）复制文件
+    cp -rn "$TMP_DIR/templates/"* "$CLAUDE_DIR/" 2>/dev/null || true
+    cp -rn "$TMP_DIR/templates/."* "$CLAUDE_DIR/" 2>/dev/null || true
+
+    # 复制 CLAUDE.md 到项目根目录
+    if [ -f "$TMP_DIR/templates/CLAUDE.md" ] && [ ! -f "$TARGET/CLAUDE.md" ]; then
+      cp "$TMP_DIR/templates/CLAUDE.md" "$TARGET/CLAUDE.md"
+    fi
+  fi
+
+  rm -rf "$TMP_DIR"
+
+else
+  echo "  ✗ 需要 git 来下载模板文件"
+  echo "  请安装 git 或使用 npx 方式: npx claude-apprentice init"
+  exit 1
+fi
+
+# ── 创建必要目录 ──────────────────────────────────────────────────────
+
+mkdir -p "$CLAUDE_DIR/reports"
+
+# ── 运行 init.sh ─────────────────────────────────────────────────────
+
+INIT_SH="$CLAUDE_DIR/scripts/init.sh"
+if [ -f "$INIT_SH" ]; then
+  echo ""
+  echo "  执行 init.sh ..."
+  echo ""
+  bash "$INIT_SH" || true
+fi
+
+# ── 完成 ──────────────────────────────────────────────────────────────
+
+echo ""
+echo "  ✓ 安装完成！"
+echo ""
+echo "  下一步:"
+echo "    1. 检查 CLAUDE.md 中的技术栈信息"
+echo "    2. 补充 .claude/memory/business-logic.md"
+echo "    3. 运行 apprentice doctor 验证"
+echo ""
+echo "  文档: https://github.com/shuoyue/claude-apprentice"
+echo ""

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "claude-apprentice",
+  "version": "1.0.0",
+  "description": "Train Claude Code into a reliable apprentice — spec-driven, memory-backed, code-reviewed.",
+  "bin": {
+    "apprentice": "./bin/apprentice.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "install.sh",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-engineering",
+    "harness",
+    "spec-driven",
+    "code-review",
+    "apprentice",
+    "agent",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shuoyue/claude-apprentice.git"
+  },
+  "homepage": "https://github.com/shuoyue/claude-apprentice#readme",
+  "bugs": {
+    "url": "https://github.com/shuoyue/claude-apprentice/issues"
+  }
+}

package/templates/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+**体系版本:** v1.0 | **更新日期:** 2026-06-22
+
+## 技术栈
+
+- 前端：待填写
+- 后端：待填写
+- 数据库：待填写
+
+## 核心原则：原生优先
+
+简单任务（改变量、修 bug、写工具函数）直接说需求，不走 workflow。
+复杂任务（新功能模块、多文件变更）才上 workflow 和 Spec。
+
+> 90% 的场景用原生 Claude Code 就够了。过度工程化是最大的浪费。
+
+## 开发铁律
+
+1. **没设计不写代码** — 动手前先确认文件、范围、方案
+2. **没测试不写代码** — 先写失败测试，再写实现
+3. **没验证不说完成** — 必须运行验证命令并贴出结果
+
+## 模式切换
+
+| 命令 | 用途 |
+|------|------|
+| `/frontend` | 前端开发 |
+| `/backend` | 后端开发 |
+| `/fullstack` | 全栈协调 |
+
+## 核心约束
+
+- 后端分层：Controller → Service → DAO，禁止跨层
+- 前端 API 调用走 `api/` 模块
+- RESTful 统一响应：`{ code, message, data, timestamp }`
+- 所有外部输入必须校验，不引入安全漏洞
+
+## 文档地图
+
+| 目录 | 用途 | 何时读 |
+|------|------|--------|
+| `.claude/rules/` | 自动触发的编码规则（索引见 `rules/INDEX.md`） | 编辑代码时自动生效 |
+| `.claude/skills/` | 完整工作流编排 | 走 workflow 时按需加载 |
+| `.claude/memory/` | 项目知识库（架构、规范、业务，含 `learned-lessons.md` 错误登记册） | 需要项目上下文时引用 |
+| `.claude/specs/` | 功能规格文档 | 中等+复杂任务时创建和引用 |
+| `.claude/scripts/` | 初始化和验证脚本 | 新项目接入时使用 |
+| `.claude/reports/` | 代码评审报告输出 | 评审完成后自动生成 |
+| `.claude/usage-guides/` | 操作手册（v1.0） | 查阅体系用法时引用 |
+| `.claude/usage-guides/bottleneck-navigation.md` | **瓶颈定位指南** | AI 效果不好时按层排查 |
+
+## 复杂度分级
+
+| 级别 | 定义 | 策略 | Prompt | Context | Harness | Loop |
+|------|------|------|--------|---------|---------|------|
+| 简单 | 单文件修改，< 30 分钟 | 原生，不走 workflow | 基础描述 | 当前文件 | rules 自动触发 | 不需要 |
+| 中等 | 新组件/新接口，30 分钟 - 2 小时 | brainstorming + spec + TDD | 完整描述 | + 相关 spec | + 验证脚本 | 通常不需要 |
+| 复杂 | 新功能模块，> 2 小时 | 完整 workflow + spec + worktree + review | 完整描述 | 全量 spec | 完整 workflow | 探索试点 |
+
+> AI 效果不好时,先按 [瓶颈定位指南](.claude/usage-guides/bottleneck-navigation.md) 排查瓶颈在哪一层,不要一上来就加 rule。

package/templates/commands/backend.md

@@ -0,0 +1,18 @@
+切换到后端开发模式。从现在起，你的工作重点是 API 接口设计、数据库操作、业务逻辑、服务治理。
+
+## 约束
+
+- 代码风格遵循 `.claude/memory/backend-standards.md`
+- 严格分层架构：Controller → Service → DAO/Mapper，禁止跨层调用
+- API 使用 RESTful 风格，统一响应格式 `{ code, message, data, timestamp }`
+- 表名小写下划线，必备字段 `id, created_at, updated_at`
+- 所有外部输入必须校验，防止 SQL 注入和 XSS
+
+## 下一步
+
+- **简单任务**（修接口/加字段）：直接描述需求即可
+- **中等任务**（新接口/新表）：说"帮我设计一下"，会触发 brainstorming
+- **复杂任务**（新模块/重构）：说"帮我规划"，会走完整流程
+- **完整流程**：调用 `/backend-workflow` 走结构化开发流水线
+
+$ARGUMENTS

package/templates/commands/frontend.md

@@ -0,0 +1,18 @@
+切换到前端开发模式。从现在起，你的工作重点是 UI 组件开发、样式调整、状态管理、前端性能优化。
+
+## 约束
+
+- 代码风格遵循 `.claude/memory/frontend-standards.md`
+- API 调用统一走 `api/` 目录模块，不直接写 HTTP 请求
+- 组件保持单一职责，PascalCase 命名，新增前先搜索已有组件
+- 处理好加载/错误/空状态三种 UI 反馈
+- ESLint + Prettier 规则不可绕过
+
+## 下一步
+
+- **简单任务**（改样式/改文案）：直接描述需求即可
+- **中等任务**（新组件/新页面）：说"帮我设计一下"，会触发 brainstorming
+- **复杂任务**（新功能模块）：说"帮我规划"，会走完整流程
+- **完整流程**：调用 `/frontend-workflow` 走结构化开发流水线
+
+$ARGUMENTS

package/templates/commands/fullstack.md

@@ -0,0 +1,18 @@
+切换到全栈协调模式。从现在起，你需要同时关注前后端一致性和完整数据流。
+
+## 约束
+
+- 后端遵循 `.claude/memory/backend-standards.md`，前端遵循 `.claude/memory/frontend-standards.md`
+- 前后端数据格式必须统一，接口契约必须一致
+- 开发顺序：数据库 → 后端 API → 前端页面，自底向上
+- 前端 API 调用必须与后端接口定义匹配（字段名、类型、路径）
+- 错误处理链路完整：数据库异常 → 后端异常处理 → 前端错误展示
+
+## 下一步
+
+- **简单任务**（改字段/修 bug）：直接描述需求即可
+- **中等任务**（新页面+新接口）：说"帮我设计一下"，会触发 brainstorming
+- **复杂任务**（新功能模块）：说"帮我规划"，会走 brainstorming → planning → TDD 完整流程
+- **完整流程**：调用 `/fullstack-workflow` 走结构化全栈开发流水线
+
+$ARGUMENTS

package/templates/commands/scan-todos.md

@@ -0,0 +1,123 @@
+---
+description: 扫描项目中的 TODO/FIXME 并归类,试点 Loop 层自动化
+---
+
+# 扫描 TODO/FIXME
+
+你现在进入 **Loop 试点模式**,扫描项目里的 TODO/FIXME,产出可执行清单。这是 Loop 层的第一个试点,验证"AI 自己驱动重复性任务"是否可行。
+
+## 你要做的事
+
+1. **扫描范围:** 当前项目根目录下所有源代码文件
+2. **排除目录(避免噪声):**
+   - `node_modules` / `dist` / `target` / `build` / `.git`(生成/依赖目录)
+   - `.claude/reports`(本扫描的输出目录)
+   - **`.claude/commands` / `.claude/usage-guides`**(命令文档和操作手册自身含 `TODO`/`FIXME` 关键字,会造成自指噪声 — 这是 v1 试点踩过的坑)
+3. **匹配模式:** `TODO`、`FIXME`、`XXX`、`HACK`、`@deprecated`、`待实现`、`待补充`、`未完成`
+4. **归类维度:**
+   - 按紧急度:FIXME > TODO > 其他
+   - 按文件:统计每个文件的待办密度
+   - 按内容关键词:是否含"性能""安全""并发""测试""幂等"等关键字
+
+## 自指过滤(重要)
+
+扫描类命令容易"扫到自己头上"。即使排除了上面的目录,仍可能遇到:
+
+- 测试 fixture / 示例代码 里的关键字
+- 文档引用其他命令时提到的关键字
+- README/变更日志里描述命令时用到的关键字
+
+**判定规则:** 如果一条匹配明显是文档/示例性质(不是真实待办),归类为**文档自指噪声**,不算真实待办,但要在报告里单独说明(这是工程改进的信号,不是无价值数据)。
+
+## 输出格式
+
+根据真实待办数选择模板:
+
+### 情况 A:真实待办 > 0
+
+产出 Markdown 报告到 `.claude/reports/todo-scan-{YYYYMMDD}.md`,结构:
+
+```markdown
+# TODO/FIXME 扫描报告
+
+**扫描时间:** {当前日期}
+**扫描范围:** {根目录}
+**文件总数:** {n}
+**真实待办:** {n}(FIXME: {n}, TODO: {n}, 其他: {n})
+**文档自指噪声:** {n} 条(已从真实待办中扣除)
+
+## 优先处理建议(Top 5)
+
+| # | 文件 | 行号 | 类型 | 内容 | 建议优先级 |
+|---|------|------|------|------|-----------|
+| 1 | ... | ... | FIXME | ... | 高 |
+
+## 按文件分布(待办密度 Top 10)
+
+| 文件 | 待办数 | 主要类型 |
+|------|--------|---------|
+
+## 按关键字聚类
+
+- 性能相关: {n} 条
+- 安全相关: {n} 条
+- 测试相关: {n} 条
+- 并发/幂等: {n} 条
+- 其他: {n} 条
+
+## 下一步建议
+
+- 立即处理: {列出 FIXME}
+- 本周处理: {列出带优先级的 TODO}
+- 可沉淀为 rule: {如果是"AI 老忘的事",建议加到 rules/}
+```
+
+### 情况 B:真实待办 = 0(全部是噪声或目录无源代码)
+
+用**简化模板**,重点是反思而非清单:
+
+```markdown
+# TODO/FIXME 扫描报告
+
+**扫描时间:** {当前日期}
+**扫描范围:** {根目录}
+**文件总数:** {n}
+**真实待办:** 0
+**文档自指噪声:** {n} 条
+
+## 关键发现
+
+{说明为什么真实待办为 0:目录性质?代码很干净?扫描范围错?}
+
+## 噪声来源(如有)
+
+| 文件 | 出现行 | 性质 |
+|------|--------|------|
+
+## 下一步建议
+
+- {根据情况给建议:换目录跑?改进命令?配 cron?}
+```
+
+## 不要做的事
+
+- ❌ 不要修改任何源代码
+- ❌ 不要建议具体修复方案(只归类,不修)
+- ❌ 不要扫描 `node_modules` / `dist` / `target` 等生成目录
+- ❌ 不要把"待办为 0"当成问题 — 这只是扫描,不是整改
+- ❌ **不要把文档自指噪声当成真实待办**(v1 试点踩过的坑)
+
+## 试点意义
+
+这是 Loop 层的第一个试点。验证三件事:
+
+1. AI 能否标准化地产出报告(可重复性)
+2. 报告是否真的有用(用户价值)
+3. 是否值得未来配 cron 定时跑(自动化潜力)
+
+跑完报告后,简单总结你的观察:这次扫描有什么意外发现?有没有反复出现的"AI 老忘的事"值得沉淀成 rule?
+
+## 版本历史
+
+- **v1**(2026-06-22):初版。在体系目录跑试点,发现自指噪声问题(12 条匹配全是文档自身)
+- **v2**(2026-06-22):基于 v1 发现改进 — 排除目录加 `.claude/commands` 和 `.claude/usage-guides`;加自指过滤判定规则;报告模板分情况 A/B

package/templates/commands/spec.md

@@ -0,0 +1,88 @@
+强制进入 Spec 模式：把模糊需求转化为结构化规格文档，作为团队和 AI 共享的唯一真相来源。
+
+## 触发场景
+
+- 只想先把需求理清楚，不想立刻动手编码
+- 多人协作时先对齐需求再分发任务
+- 想把 spec 作为给其他 AI 会话/同事的需求文档
+- 不信任 AI 的复杂度判断，要强制产出 spec
+
+## 执行流程
+
+### 步骤 1：读取规范
+
+读取 `.claude/specs/SPEC-GUIDE.md`，确认 spec 文件格式和生命周期定义。
+
+### 步骤 2：需求澄清（必须完成，不得跳过）
+
+通过苏格拉底式对话澄清以下内容（按需提问，不要一次全部问完）：
+
+- **目标**：这个功能要解决什么问题？谁是使用者？
+- **范围**：包含什么、不包含什么？边界在哪里？
+- **接口**：涉及哪些 API？输入输出是什么？
+- **数据**：涉及哪些表/字段/索引？有无迁移？
+- **约束**：硬性约束（性能、安全、幂等、并发、兼容性）
+- **验收**：怎样才算完成？可验证的标准是什么？
+
+如果用户在 `$ARGUMENTS` 中已经提供了足够信息，可以直接进入步骤 3，但要显式列出"我理解的关键点"让用户确认。
+
+### 步骤 3：产出 spec 文件
+
+在 `.claude/specs/active/` 下创建 `[feature-name].md`，使用 kebab-case 命名。文件必须包含 `SPEC-GUIDE.md` 中定义的完整结构：
+
+```markdown
+# [功能名称] 规格
+
+## 状态
+Proposed
+
+## 需求概述
+[一句话描述]
+
+## 涉及文件
+- 新增：[路径列表]
+- 修改：[路径列表]
+
+## 接口定义（如涉及 API）
+## 数据模型变更（如涉及数据库）
+## 约束条件
+## 验收标准
+## 变更记录
+| 日期 | 变更内容 |
+|------|---------|
+| YYYY-MM-DD | 初始提案 |
+```
+
+### 步骤 4：等待用户确认
+
+明确告知用户 spec 已创建，**不要主动进入实施阶段**。提示用户：
+
+- "请确认 spec 内容，或指出需要调整的部分"
+- "确认后说'开始实现'，我会把状态改为 Applied 并进入 workflow"
+
+### 步骤 5：确认后
+
+- 用户确认 → 状态改为 `Applied`
+- 用户要求修改 → 更新 spec 的"变更记录"表（Delta Spec 原则，不重写整个文档）
+- 用户说"开始实现" → 进入对应 workflow（根据技术栈调用 `/backend` / `/frontend` / `/fullstack`）
+
+## 关键约束
+
+- **不得跳过澄清直接写 spec**：本命令的核心价值就是把需求理清
+- **不得在 spec 阶段写代码**：spec 模式只产出文档，不产出实现
+- **必须遵循 Delta Spec 原则**：每次修改追加到变更记录，不重写整个文档
+- **必须使用 kebab-case 命名**：如 `user-points-credit.md`，不用空格或下划线
+- **必须读取 SPEC-GUIDE.md**：每次执行都要读，防止格式漂移
+
+## 与 workflow 的区别
+
+| 入口 | 行为 |
+|------|------|
+| `/spec <需求>` | 只产出 spec 文件，不进入实现 |
+| `/backend` `/frontend` `/fullstack` | 走完整 workflow（spec + 实现 + 验证 + 归档） |
+
+`/spec` 是"先把事说清"，workflow 是"说清后把事做完"。
+
+## 输入
+
+$ARGUMENTS

package/templates/memory/architecture.md

@@ -0,0 +1,55 @@
+# 项目架构文档
+
+## 系统概述
+
+[在此描述项目的主要功能和目标]
+
+## 技术架构
+
+### 整体架构
+[描述系统的分层架构、模块划分]
+
+### 技术栈
+
+#### 前端技术栈
+- 框架：[Vue/React/Angular等]
+- 状态管理：[Vuex/Redux等]
+- 构建工具：[Vite/Webpack等]
+
+#### 后端技术栈
+- 语言：[Java/Go/Python等]
+- 框架：[SpringBoot/Gin/FastAPI等]
+- 数据库：[MySQL/PostgreSQL等]
+- 中间件：[Redis/RabbitMQ等]
+
+## 目录结构
+
+```
+[项目根目录]/
+├── frontend/          # 前端代码
+│   ├── src/
+│   │   ├── components/  # 组件
+│   │   ├── views/       # 页面
+│   │   └── api/         # API调用
+│   └── package.json
+├── backend/           # 后端代码
+│   ├── src/main/java/
+│   │   ├── controller/  # 控制器
+│   │   ├── service/     # 服务层
+│   │   └── dao/         # 数据访问层
+│   └── pom.xml
+└── docs/              # 文档
+```
+
+## 模块依赖关系
+
+[描述各模块之间的依赖关系]
+
+## 部署架构
+
+[描述系统的部署方式、环境配置等]
+
+---
+
+**最后更新:** 2026-05-18
+**维护者:** [填写]

package/templates/memory/backend-standards.md

@@ -0,0 +1,84 @@
+# 后端开发规范
+
+## API设计规范
+
+### RESTful API 设计原则
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/resources | 获取列表 |
+| GET | /api/resources/:id | 获取详情 |
+| POST | /api/resources | 创建资源 |
+| PUT | /api/resources/:id | 更新资源 |
+| DELETE | /api/resources/:id | 删除资源 |
+
+### 接口响应格式
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {},
+  "timestamp": 1234567890
+}
+```
+
+## 代码分层规范
+
+### Controller 层
+- 职责：接收请求、参数校验、调用Service、返回响应
+- 命名：*Controller.java
+
+### Service 层
+- 职责：业务逻辑处理
+- 命名：*Service.java, *ServiceImpl.java
+
+### DAO/Mapper 层
+- 职责：数据访问
+- 命名：*Mapper.java, *Mapper.xml
+
+## 数据库规范
+
+### 表命名
+- 小写字母 + 下划线：user_profile
+
+### 字段命名
+- 小写字母 + 下划线：created_at
+
+### 必备字段
+- id: 主键
+- created_at: 创建时间
+- updated_at: 更新时间
+- is_deleted: 逻辑删除标记
+
+## 异常处理规范
+
+### 异常分类
+- BusinessException：业务异常
+- SystemException：系统异常
+- ValidationException：参数校验异常
+
+### 全局异常处理
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(Exception.class)
+    public Result handleException(Exception e) {
+        // 处理逻辑
+    }
+}
+```
+
+## 日志规范
+
+### 日志级别
+- ERROR：错误信息
+- WARN：警告信息
+- INFO：关键业务信息
+- DEBUG：调试信息
+
+### 日志格式
+```[时间] [级别] [类名] - 日志内容```
+
+---
+
+**最后更新:** 2026-05-18

package/templates/memory/business-logic.md

@@ -0,0 +1,59 @@
+# 业务逻辑说明
+
+## 核心业务流程
+
+### 业务流程1：[流程名称]
+
+```
+[开始] → [步骤1] → [步骤2] → [步骤3] → [结束]
+```
+
+**详细说明：**
+1. 用户触发[操作]
+2. 系统执行[处理]
+3. 返回[结果]
+
+## 数据流向
+
+### 前端 → 后端数据流
+
+```
+前端页面 → API接口 → Controller → Service → DAO → 数据库
+```
+
+### 关键数据结构
+
+| 数据项 | 类型 | 说明 | 来源 |
+|--------|------|------|------|
+| 字段1 | String | 说明 | 前端传入 |
+| 字段2 | Integer | 说明 | 数据库查询 |
+
+## 业务规则
+
+### 规则1：[规则名称]
+- 条件：[触发条件]
+- 处理：[处理方式]
+- 示例：[示例说明]
+
+### 规则2：[规则名称]
+- 条件：[触发条件]
+- 处理：[处理方式]
+- 示例：[示例说明]
+
+## 权限控制
+
+### 角色定义
+- 管理员：全部权限
+- 普通用户：部分权限
+
+### 权限矩阵
+
+| 操作 | 管理员 | 普通用户 | 访客 |
+|------|--------|----------|------|
+| 创建 | ✓ | ✓ | ✗ |
+| 编辑 | ✓ | ✗ | ✗ |
+| 删除 | ✓ | ✗ | ✗ |
+
+---
+
+**最后更新:** 2026-05-18