claude-apprentice 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Planned
+- Team collaboration features (shared spec workspace)
+- Cursor native support
+- Web UI generator (configure .claude/ visually)
+
+---
+
+## [1.0.0] — 2026-06-22
+
+First public release. Open-sourced from internal v5.7.
+
+### Added — Core Workflow
+- **Spec-driven development** (`commands/spec.md`)
+  - Lifecycle: PROPOSE → APPLY → SHIP → ARCHIVE
+  - Template with `Why`, `Scope`, `API`, `Acceptance Criteria`, `Risks`
+  - Delta spec support for incremental changes
+- **6-phase workflow** (`workflow/WORKFLOW-GUIDE.md`)
+  - Brainstorm → Plan → TDD → Validate → Self-Review → Hand-off
+  - Specialized entry points: `/frontend`, `/backend`, `/fullstack`
+- **6-dimension code review** (`skills/code-review/`)
+  - Security (18), Correctness (5), Performance (4), Design (4), Maintainability (6), Convention (3)
+  - Severity levels: CRITICAL / HIGH / MEDIUM / LOW
+  - Markdown + Excel export
+
+### Added — Memory System
+- **Error-driven knowledge base** (`memory/learned-lessons.md`)
+  - Format: Symptom / Root cause / Rule
+  - 8 seed lessons (L-001 ~ L-008)
+- **Project memory** (`memory/architecture.md`)
+  - System map, invariants, critical paths, conventions, gotchas
+
+### Added — Discipline Layer
+- **Coding standards** (`rules/coding-standards.md`)
+  - Universal, type safety, function hygiene, file hygiene, testing, git
+- **Git safety** (`rules/git-safety.md`)
+  - Forbidden destructive ops (force push, hard reset, branch -D)
+  - Branch naming, commit message format, pre-commit hook rules
+
+### Added — Tooling
+- **CLI** (`bin/apprentice.js`)
+  - `init`, `update`, `doctor`, `version`, `help`
+  - Zero-dependency (Node >= 14)
+  - Auto project type detection (Java/Node/Go/Python/Rust/Generic)
+- **One-line installer** (`install.sh`)
+  - `curl | bash` workflow
+  - Git clone preferred, curl fallback
+  - Auto-backup existing `.claude/`
+- **Health check** (`scripts/health-check.sh`)
+  - Standalone — runs anywhere without Node
+
+### Added — Documentation
+- **README.md** — full feature overview with quick start
+- **LICENSE** — MIT
+- **CHANGELOG.md** — this file
+- **CONTRIBUTING.md** — contribution guidelines (TODO)
+
+### Migration
+Project is a clean-slate open-source version of an internal tool (`tsc-toolkit`) that was iterated through v5.2 → v5.7. All proprietary/company-specific references have been removed.
+
+### Lessons Carried Over
+8 seed lessons (L-001 ~ L-008) distilled from ~50 hours of real-world Claude Code usage across Java Spring, Vue/React frontend, and Node.js backend projects.
+
+---
+
+## Version History (Pre-open-source)
+
+These versions were internal and not publicly released. Documented here for context.
+
+### v5.7 (internal, 2026-06-10)
+- Refined workflow phases
+- Added 6-dimension code review (was 5)
+- Fixed: spec drift problem (specs going stale)
+
+### v5.6 (internal, 2026-05-22)
+- Added project type auto-detection
+- Added multi-project workspace support
+- Added health check command
+
+### v5.5 (internal, 2026-05-01)
+- Refactored `learned-lessons.md` format
+- Added L-005 ~ L-007
+- Added git safety rules
+
+### v5.4 (internal, 2026-04-12)
+- Added spec-driven development lifecycle
+- Added delta spec support
+
+### v5.3 (internal, 2026-03-20)
+- Compressed CLAUDE.md from 200+ lines to 53 lines
+- Moved knowledge to memory/
+
+### v5.2 (internal, 2026-03-01)
+- Initial 4-layer architecture (CLAUDE.md + commands + rules + skills)
+
+### Pre-v5.2
+- Chaos. No structure. AI freelanced constantly. Many late nights.
+
+---
+
+[Unreleased]: https://github.com/shuoyue/claude-apprentice/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/shuoyue/claude-apprentice/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 claude-apprentice contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# claude-apprentice
+
+> Train Claude Code into a reliable apprentice — spec-driven, memory-backed, code-reviewed.
+
+[![npm version](https://img.shields.io/npm/v/claude-apprentice.svg)](https://www.npmjs.com/package/claude-apprentice)
+[![GitHub stars](https://img.shields.io/github/stars/shuoyue/claude-apprentice.svg)](https://github.com/shuoyue/claude-apprentice/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D14-green)](https://nodejs.org)
+
+AI 驱动全栈开发工程化体系 — 一条命令初始化项目。
+
+基于"三件套"（Claude Code + Superpowers + Spec）构建的轻量级 Harness 体系，解决 LLM 不可控和无状态的缺陷，让 AI 从"聊天玩具"进化为"可靠开发员工"。
+
+---
+
+## 快速开始
+
+### 推荐方式（npx）
+
+```bash
+cd your-project
+npx claude-apprentice init
+```
+
+### curl 一键安装（非 Node.js 用户）
+
+```bash
+cd your-project
+curl -fsSL https://raw.githubusercontent.com/shuoyue/claude-apprentice/main/install.sh | bash
+```
+
+### 初始化后做什么
+
+1. 检查 `CLAUDE.md` 中的技术栈信息
+2. 补充 `.claude/memory/business-logic.md` 中的业务逻辑
+3. 打开 Claude Code 直接开始工作
+
+---
+
+## 体系架构
+
+### 三层架构
+
+| 层级 | 对应 | 职责 |
+|------|------|------|
+| **执行底盘** | Claude Code + `scripts/` | 文件读写、沙箱隔离、工具调用 — 让 AI 能操作真实世界 |
+| **行为纪律** | `rules/` + Superpowers | TDD、代码审查、系统化调试 — 让 AI 不犯野路子错误 |
+| **规格对齐** | `specs/`（`SPEC-GUIDE.md`）+ `memory/` + `CLAUDE.md` | 结构化需求文档作为共享锚点 — 防止理解偏差 |
+
+### 核心原则：原生优先
+
+> **90% 的场景用原生 Claude Code 就够了。过度工程化是最大的浪费。**
+
+| 复杂度 | 定义 | 策略 |
+|--------|------|------|
+| **简单** | 单文件修改，< 30 分钟 | 直接说需求，不走 workflow |
+| **中等** | 新组件/新接口，30 分钟 - 2 小时 | brainstorming + spec + TDD |
+| **复杂** | 新功能模块，> 2 小时 | 完整 workflow + spec + worktree + review |
+
+### 开发铁律
+
+1. **没设计不写代码** — 动手前先确认文件、范围、方案
+2. **没测试不写代码** — 先写失败测试，再写实现
+3. **没验证不说完成** — 必须运行验证命令并贴出结果
+
+---
+
+## 日常使用
+
+### 简单任务（推荐 90% 场景）
+
+直接说需求，不用切模式：
+
+```
+你: 修复登录接口返回 500 的问题
+你: 把分页改成每页 20 条
+```
+
+### 模式切换
+
+| 命令 | 模式 | 适用场景 |
+|------|------|----------|
+| `/frontend` | 前端模式 | 页面开发、组件开发、样式调整 |
+| `/backend` | 后端模式 | 接口开发、数据库操作、业务逻辑 |
+| `/fullstack` | 全栈模式 | 新功能从 0 到 1、前后端联调 |
+| `/spec` | Spec 模式 | 只想把需求理清楚，不立刻动手编码 |
+
+### `/spec` 命令
+
+强制产出 spec 文件，不进入实现阶段：
+
+```
+你: /spec 创建用户积分入账接口，需要幂等和并发控制
+```
+
+| 入口 | 行为 |
+|------|------|
+| `/spec <需求>` | **只产出 spec，不写代码** |
+| `/backend` `/frontend` `/fullstack` | 走完整 workflow（spec + 实现 + 验证 + 归档） |
+
+### 工作流步骤
+
+| 步骤 | 名称 | 触发条件 | 产出 |
+|------|------|---------|------|
+| 0 | 需求入口 | 所有任务 | 复杂度判断 |
+| 1 | 需求澄清 + Spec | 中等+复杂 | `specs/active/[feature].md` |
+| 2 | 任务拆解 | 复杂 | 任务计划 |
+| 3 | 实现 | 所有任务 | 代码（读取 spec 作为约束） |
+| 4 | 验证 + 归档 | 所有任务 | 测试结果 + spec 移入 archived |
+
+### 代码评审
+
+自动触发或手动触发，按 7 个维度逐项检查：
+
+| 优先级 | 维度 | 项数 |
+|--------|------|------|
+| 1 | 安全性 | 18 项 |
+| 2 | 正确性 | 5 项 |
+| 3 | 性能 | 4 项 |
+| 4 | 设计与架构 | 4 项 |
+| 5 | 可维护性 | 6 项 |
+| 6 | 规范与一致性 | 3 项 |
+| 7 | 文件类型专属 | 按后缀激活 |
+
+输出 MD 或 Excel 格式报告到 `.claude/reports/`。
+
+---
+
+## Spec 规格驱动
+
+> 规格是唯一的真相来源。AI 每次从 spec 文件读约束，不靠聊天记录。
+
+```
+Propose（提案）→ Apply（实施）→ Archive（归档）
+```
+
+| 阶段 | 触发方式 | 做什么 |
+|------|---------|--------|
+| **Propose** | `/spec` 命令 或 workflow 步骤 1 | 在 `specs/active/` 创建 spec 文件 |
+| **Apply** | 用户确认 spec 后 | 状态改为 Applied，后续 Session 从文件读约束 |
+| **Archive** | workflow 最后一步 | 移入 `specs/archived/`，作为活文档保留 |
+
+---
+
+## 错题本机制
+
+每一条 `rules/` 和 `learned-lessons.md` 中的规则都对应一个真实失败案例：
+
+```markdown
+### L-001: AI 先写实现再补测试
+- 错误现象：AI 直接写完整个实现，然后说"接下来补测试"
+- 根因：没有强制 TDD 流程，AI 倾向走捷径
+- 规避规则：workflow 步骤 3 必须先写失败测试，看到红灯再写实现
+```
+
+**机制闭环**：AI 犯错 → 加一条规则 → 以后不再犯同类错误。
+
+---
+
+## CLI 命令
+
+```bash
+apprentice init                # 初始化项目（复制模板 + 运行 init.sh）
+apprentice update              # 增量更新（不覆盖已有文件）
+apprentice doctor              # 运行健康检查
+apprentice version             # 显示版本号
+apprentice help                # 显示帮助
+```
+
+---
+
+## 项目初始化后的目录结构
+
+```
+your-project/
+├── CLAUDE.md                       # [自动加载] 项目最高优先级指令
+└── .claude/
+    ├── settings.json               # 主配置（团队共享，提交 git）
+    ├── MEMORY.md                   # 知识库索引
+    ├── commands/                   # 斜杠命令
+    │   ├── frontend.md             #   /frontend
+    │   ├── backend.md              #   /backend
+    │   ├── fullstack.md            #   /fullstack
+    │   ├── spec.md                 #   /spec
+    │   └── scan-todos.md           #   /scan-todos (Loop 层试点)
+    ├── rules/                      # 条件规则（自动触发）
+    │   ├── INDEX.md                #   规则触发索引
+    │   ├── coding-standards.md     #   编码标准
+    │   ├── git-safety.md           #   Git 安全
+    │   └── superpowers-workflow.md #   工作流 + 调试规则
+    ├── skills/                     # 工作流技能
+    │   ├── frontend-workflow.md
+    │   ├── backend-workflow.md
+    │   ├── fullstack-workflow.md
+    │   └── code-review/            #   代码评审（7 维度）
+    ├── reports/                    # 评审报告输出
+    ├── specs/                      # 功能规格（Propose → Apply → Archive）
+    │   ├── SPEC-GUIDE.md
+    │   ├── active/
+    │   └── archived/
+    ├── scripts/
+    │   ├── init.sh                 # 初始化（自动检测项目类型）
+    │   ├── health-check.sh         # 健康巡检（9 项检查）
+    │   └── auto-review.sh          # PostToolUse hook 自动评审
+    ├── usage-guides/               # 操作手册
+    │   ├── README.md
+    │   ├── usage-guide-v5.8.md
+    │   └── bottleneck-navigation.md  # 瓶颈定位指南
+    └── memory/                     # 项目知识库
+        ├── architecture.md
+        ├── frontend-standards.md
+        ├── backend-standards.md
+        ├── business-logic.md
+        ├── superpowers-config.md
+        ├── learned-lessons.md      # 错误驱动的知识积累
+        └── issues.md
+```
+
+---
+
+## 多角色协同
+
+| 阶段 | 参与角色 | 做什么 | 产出 |
+|------|---------|--------|------|
+| **混沌期** (Brainstorming) | PM + Tech Lead | 苏格拉底式对话，理清业务与技术选型 | 需求共识 |
+| **规划期** (`/spec`) | PM 签收标准，Tech Lead 定方案 | 固化为 `specs/active/` 文档 | spec 文件 |
+| **执行期** (Workflow) | Developer | TDD 流程：先写测试再实现，自我审查 | 代码 + 测试 |
+| **验证期** (QA 左移) | QA | 基础单元测试已内建，专注集成/E2E/探索性测试 | 测试报告 |
+
+---
+
+## 渐进式落地
+
+| 阶段 | 时间 | 聚焦 | 做什么 |
+|------|------|------|--------|
+| **起步期** | 第 1-2 周 | 单兵作战 | 统一工具链，建立 `CLAUDE.md` + `rules/`，跑通小需求闭环 |
+| **进阶期** | 第 3-8 周 | 团队资产积累 | 封装 Skills，完善知识库和跨会话记忆 |
+| **成熟期** | 第 9 周+ | 复杂场景扩展 | 按需引入 worktree 隔离、多 Agent 协调 |
+
+---
+
+## 常见问题
+
+### `/spec` 和 `/backend` 怎么选？
+
+| 你的诉求 | 用哪个 |
+|----------|--------|
+| 只想把需求理清楚，不写代码 | `/spec` |
+| 想直接做完一个功能 | `/backend` `/frontend` `/fullstack` |
+| 多人协作，先对齐再分发 | `/spec` 写完分发 |
+
+### 新员工怎么上手？
+
+```bash
+cd your-project
+npx claude-apprentice init
+claude
+```
+
+### 团队物理隔离怎么统一环境？
+
+所有规范配置提交到 Git 仓库。新成员拉取代码后，AI 自动读取配置文件，加载出完全一致的环境。**代码即配置，Git 即分发。**
+
+### 什么时候不用这套体系？
+
+| 场景 | 建议 |
+|------|------|
+| 一次性脚本 | 直接写，跑通即可 |
+| 探索性原型 | 快速验证，不走 spec |
+| 紧急 Hotfix | 先修复，事后补测试和 spec |
+
+---
+
+## 兼容性
+
+- ✅ **Claude Code** — 原生（slash commands + skills）
+- ⚠️ **Cursor** — 手动（模板可用，无 slash commands）
+- ⚠️ **GitHub Copilot Chat** — 手动（模板可用）
+- ⚠️ **Windsurf** — 手动（模板可用）
+
+---
+
+## 版本更新
+
+```bash
+# 增量更新，已有文件不覆盖
+apprentice update
+```
+
+## 详细文档
+
+- 完整使用手册见 `templates/usage-guides/` 目录
+- 版本演进史见 [CHANGELOG.md](./CHANGELOG.md)
+
+---
+
+## 相关
+
+- **Blog (中文)**: 公众号「造物手记」— author's writings on AI engineering
+- **Mitchell Hashimoto's [AGENTS.md](https://github.com/mitchellh/agentkit)** — inspiration for `learned-lessons.md`
+- **Anthropic's [Claude Code Skills](https://docs.claude.com/en/docs/agents-and-tools/claude-code/skills)** — the underlying mechanism
+
+---
+
+## License
+
+[MIT](./LICENSE) — © 2026
+
+---
+
+_Made with discipline. Crafted over 5 internal versions (v5.2 → v5.8), open-sourced as v1.0._

package/bin/apprentice.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const PKG = require('../package.json');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function log(msg) { console.log(`  ${msg}`); }
+function ok(msg) { console.log(`\x1b[32m  ✓\x1b[0m ${msg}`); }
+function warn(msg) { console.log(`\x1b[33m  ⚠\x1b[0m ${msg}`); }
+function err(msg) { console.error(`\x1b[31m  ✗\x1b[0m ${msg}`); }
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    if (entry === '.DS_Store') continue;
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      if (!fs.existsSync(destPath)) {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+function getTargetDir() {
+  return process.cwd();
+}
+
+// ── Commands ─────────────────────────────────────────────────────────
+
+function cmdInit(args) {
+  const target = getTargetDir();
+  const claudeDir = path.join(target, '.claude');
+
+  log(`目标目录: ${target}`);
+  log('');
+
+  // 1. 复制模板文件到 .claude/（增量：已有文件不覆盖）
+  ok('复制模板文件...');
+  copyDir(TEMPLATES_DIR, claudeDir);
+
+  // 2. 复制 CLAUDE.md 到项目根目录
+  const rootClaude = path.join(TEMPLATES_DIR, 'CLAUDE.md');
+  const targetClaude = path.join(target, 'CLAUDE.md');
+  if (fs.existsSync(rootClaude) && !fs.existsSync(targetClaude)) {
+    fs.copyFileSync(rootClaude, targetClaude);
+    ok('创建 CLAUDE.md');
+  } else if (fs.existsSync(targetClaude)) {
+    warn('CLAUDE.md 已存在，跳过');
+  }
+
+  // 3. 创建 reports 目录
+  const reportsDir = path.join(claudeDir, 'reports');
+  if (!fs.existsSync(reportsDir)) {
+    fs.mkdirSync(reportsDir, { recursive: true });
+    ok('创建 reports/ 目录');
+  }
+
+  // 4. 执行 init.sh
+  const initSh = path.join(claudeDir, 'scripts', 'init.sh');
+  if (fs.existsSync(initSh)) {
+    log('');
+    ok('执行 init.sh ...');
+    log('');
+    try {
+      execSync(`bash "${initSh}"`, { cwd: target, stdio: 'inherit' });
+    } catch (e) {
+      warn('init.sh 执行中出现警告（可忽略）');
+    }
+  }
+
+  log('');
+  ok('初始化完成！');
+  log('');
+  log('下一步:');
+  log('  1. 检查 CLAUDE.md 中的技术栈信息');
+  log('  2. 补充 .claude/memory/business-logic.md');
+  log('  3. 运行 apprentice doctor 验证');
+}
+
+function cmdUpdate() {
+  const target = getTargetDir();
+  const claudeDir = path.join(target, '.claude');
+
+  if (!fs.existsSync(claudeDir)) {
+    err('.claude/ 目录不存在，请先运行 apprentice init');
+    process.exit(1);
+  }
+
+  log('增量更新...');
+  copyDir(TEMPLATES_DIR, claudeDir);
+
+  const initSh = path.join(claudeDir, 'scripts', 'init.sh');
+  if (fs.existsSync(initSh)) {
+    log('');
+    try {
+      execSync(`bash "${initSh}"`, { cwd: target, stdio: 'inherit' });
+    } catch (e) {
+      warn('init.sh 执行中出现警告（可忽略）');
+    }
+  }
+
+  log('');
+  ok('更新完成！');
+}
+
+function cmdDoctor() {
+  const target = getTargetDir();
+  const checkSh = path.join(target, '.claude', 'scripts', 'health-check.sh');
+
+  if (!fs.existsSync(checkSh)) {
+    err('.claude/scripts/health-check.sh 不存在，请先运行 apprentice init');
+    process.exit(1);
+  }
+
+  log('运行健康检查...');
+  log('');
+  try {
+    execSync(`bash "${checkSh}"`, { cwd: target, stdio: 'inherit' });
+  } catch (e) {
+    // health-check.sh may exit with non-zero on failures
+  }
+}
+
+function cmdVersion() {
+  console.log(`claude-apprentice v${PKG.version}`);
+}
+
+function cmdHelp() {
+  console.log(`
+\x1b[1mclaude-apprentice\x1b[0m v${PKG.version} — Train Claude Code into a reliable apprentice
+
+\x1b[1m用法:\x1b[0m
+  apprentice <command> [options]
+
+\x1b[1m命令:\x1b[0m
+  init                初始化当前项目（复制模板 + 运行 init.sh）
+  update              增量更新（不覆盖已有文件）
+  doctor              运行健康检查
+  version             显示版本号
+  help                显示帮助信息
+
+\x1b[1m使用方式:\x1b[0m
+  # npx 直接运行（推荐）
+  npx claude-apprentice init
+
+  # curl 一键安装（非 Node.js 用户）
+  curl -fsSL https://raw.githubusercontent.com/shuoyue/claude-apprentice/main/install.sh | bash
+
+  # 本地开发
+  node bin/apprentice.js init
+
+\x1b[1m文档:\x1b[0m
+  https://github.com/shuoyue/claude-apprentice
+`);
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'init':
+    cmdInit(args.slice(1));
+    break;
+  case 'update':
+    cmdUpdate();
+    break;
+  case 'doctor':
+    cmdDoctor();
+    break;
+  case 'version':
+  case '-v':
+  case '--version':
+    cmdVersion();
+    break;
+  case 'help':
+  case '-h':
+  case '--help':
+  case undefined:
+    cmdHelp();
+    break;
+  default:
+    err(`未知命令: ${command}`);
+    console.log('运行 apprentice help 查看可用命令');
+    process.exit(1);
+}