claude-sdlc 1.0.6 → 1.0.7

package/lib/installer.js

@@ -74,11 +74,11 @@ function resultBanner(text, ok = true) {
 
 // ── 工具函数 ──────────────────────────────────────────
 
-function hookGroupKey(group) {
-  if (group.hooks && Array.isArray(group.hooks)) {
-    return group.hooks.map(h => h.command || h.prompt).join('|');
-  }
-  return group.command || group.prompt || JSON.stringify(group);
+/**
+ * 获取 hook 组的 matcher 标识（用于按 matcher 匹配升级，而非按内容去重）
+ */
+function hookMatcherKey(group) {
+  return group.matcher || '';
 }
 
 function mergeSettings(existing, template) {
@@ -92,16 +92,36 @@ function mergeSettings(existing, template) {
 
   for (const type of hookTypes) {
     const existingHooks = result.hooks?.[type] || [];
-    const newHooks = template.hooks?.[type] || [];
+    const templateHooks = template.hooks?.[type] || [];
+
+    // 按 matcher 建立模板 hook 索引
+    const templateByMatcher = new Map();
+    for (const hook of templateHooks) {
+      templateByMatcher.set(hookMatcherKey(hook), hook);
+    }
 
-    const merged = [...existingHooks];
-    const existingKeys = new Set(existingHooks.map(hookGroupKey));
+    const merged = [];
+    const processedMatchers = new Set();
 
-    for (const hook of newHooks) {
-      const key = hookGroupKey(hook);
-      if (!existingKeys.has(key)) {
+    // 遍历已有 hooks：模板有同 matcher → 替换为模板版本；模板没有 → 保留（用户自定义）
+    for (const hook of existingHooks) {
+      const mk = hookMatcherKey(hook);
+      if (processedMatchers.has(mk)) continue;
+      processedMatchers.add(mk);
+
+      if (templateByMatcher.has(mk)) {
+        merged.push(JSON.parse(JSON.stringify(templateByMatcher.get(mk))));
+      } else {
         merged.push(hook);
-        existingKeys.add(key);
+      }
+    }
+
+    // 追加模板中新增的 hooks（已有中没有的 matcher）
+    for (const hook of templateHooks) {
+      const mk = hookMatcherKey(hook);
+      if (!processedMatchers.has(mk)) {
+        processedMatchers.add(mk);
+        merged.push(JSON.parse(JSON.stringify(hook)));
       }
     }
 
@@ -112,46 +132,6 @@ function mergeSettings(existing, template) {
   return result;
 }
 
-/**
- * 从 CLAUDE.md 中提取 YAML 状态块（```yaml ... ``` 包裹的 SDLC 项目状态）
- */
-function extractYamlState(content) {
-  const match = content.match(/```yaml\n# === SDLC 项目状态 ===\n[\s\S]*?```/);
-  return match ? match[0] : null;
-}
-
-/**
- * 判断 YAML 状态块是否有实际项目数据（非空白模板）
- */
-function hasActiveState(yamlBlock) {
-  if (!yamlBlock) return false;
-  // 检查 current_phase 是否不是 P0
-  if (/current_phase:\s*P[1-6]/.test(yamlBlock)) return true;
-  // 检查 task_description 是否非空
-  if (/task_description:\s*"[^"]+"/.test(yamlBlock)) return true;
-  // 检查 modified_files 是否有内容
-  if (/modified_files:\s*\n\s*-/.test(yamlBlock)) return true;
-  // 检查 prd 是否有实际条目（非注释）
-  if (/prd:\s*\n\s*-\s*id:/.test(yamlBlock)) return true;
-  return false;
-}
-
-/**
- * 合并 CLAUDE.md — 更新模板指令，保留用户的 YAML 状态块
- */
-function mergeClaudeMd(existingContent, templateContent) {
-  const existingState = extractYamlState(existingContent);
-  const templateState = extractYamlState(templateContent);
-
-  if (!existingState || !templateState) {
-    // 格式不匹配，无法合并，返回模板
-    return templateContent;
-  }
-
-  // 用旧的状态块替换新模板中的空白状态块
-  return templateContent.replace(templateState, existingState);
-}
-
 function copyFilesQuiet(srcDir, destDir, ext) {
   if (!fs.existsSync(srcDir)) return [];
   const files = fs.readdirSync(srcDir).filter(f => f.endsWith(ext));
@@ -165,7 +145,7 @@ function copyFilesQuiet(srcDir, destDir, ext) {
 
 function install(targetDir) {
   const templateDir = path.join(__dirname, '..', 'template');
-  const STEPS = 6;
+  const STEPS = 7;
 
   // 验证
   if (!fs.existsSync(targetDir)) {
@@ -191,31 +171,16 @@ function install(targetDir) {
   console.log(`  ${SYM.arrow} 目标  ${BOLD}${targetDir}${RESET}`);
   blank();
 
-  // Step 1: CLAUDE.md（智能合并：更新模板指令，保留项目状态）
+  // Step 1: CLAUDE.md（纯控制指令，升级时直接替换为最新版本）
   step(1, STEPS, '安装核心控制文件');
   const targetClaudeMd = path.join(targetDir, 'CLAUDE.md');
   const templateClaudeMd = path.join(templateDir, 'CLAUDE.md');
   const templateContent = fs.readFileSync(templateClaudeMd, 'utf-8');
-
-  if (fs.existsSync(targetClaudeMd)) {
-    const existingContent = fs.readFileSync(targetClaudeMd, 'utf-8');
-    const existingState = extractYamlState(existingContent);
-
-    if (hasActiveState(existingState)) {
-      // 有活跃项目状态 → 更新指令模板，保留状态块
-      const merged = mergeClaudeMd(existingContent, templateContent);
-      fs.writeFileSync(targetClaudeMd, merged, 'utf-8');
-      fileLog(SYM.check, `CLAUDE.md ${DIM}(升级模板，保留项目状态)${RESET}`);
-    } else {
-      // 状态为空（P0）→ 直接覆盖
-      fs.writeFileSync(targetClaudeMd, templateContent, 'utf-8');
-      fileLog(SYM.check, 'CLAUDE.md');
-    }
-  } else {
-    // 首次安装
-    fs.writeFileSync(targetClaudeMd, templateContent, 'utf-8');
-    fileLog(SYM.check, 'CLAUDE.md');
-  }
+  const isUpgrade = fs.existsSync(targetClaudeMd);
+  fs.writeFileSync(targetClaudeMd, templateContent, 'utf-8');
+  fileLog(SYM.check, isUpgrade
+    ? `CLAUDE.md ${DIM}(已更新至最新版本)${RESET}`
+    : 'CLAUDE.md');
 
   // Step 2: 目录结构
   step(2, STEPS, '创建目录结构');
@@ -225,8 +190,19 @@ function install(targetDir) {
     fileLog(SYM.check, `.claude/${dir}/`);
   }
 
-  // Step 3: 规则文件
-  step(3, STEPS, '安装规则文件');
+  // Step 3: project-state.md（项目状态文件 — 已有则跳过，保护用户数据）
+  step(3, STEPS, '初始化项目状态文件');
+  const targetState = path.join(targetDir, '.claude', 'project-state.md');
+  const templateState = path.join(templateDir, '.claude', 'project-state.md');
+  if (fs.existsSync(targetState)) {
+    fileLog(SYM.check, `.claude/project-state.md ${DIM}(已有状态，跳过保护)${RESET}`);
+  } else {
+    fs.copyFileSync(templateState, targetState);
+    fileLog(SYM.check, '.claude/project-state.md');
+  }
+
+  // Step 4: 规则文件
+  step(4, STEPS, '安装规则文件');
   const rules = copyFilesQuiet(
     path.join(templateDir, '.claude', 'rules'),
     path.join(targetDir, '.claude', 'rules'),
@@ -234,8 +210,8 @@ function install(targetDir) {
   );
   fileLog(SYM.check, `${rules.length} 个规则文件`);
 
-  // Step 4: Hook 脚本
-  step(4, STEPS, '安装 Hook 脚本');
+  // Step 5: Hook 脚本
+  step(5, STEPS, '安装 Hook 脚本');
   const hooksSrcDir = path.join(templateDir, '.claude', 'hooks');
   const hooksDestDir = path.join(targetDir, '.claude', 'hooks');
   let hookCount = 0;
@@ -250,8 +226,8 @@ function install(targetDir) {
   }
   fileLog(SYM.check, `${hookCount} 个 Hook 脚本`);
 
-  // Step 5: 斜杠命令
-  step(5, STEPS, '安装斜杠命令');
+  // Step 6: 斜杠命令
+  step(6, STEPS, '安装斜杠命令');
   const cmds = copyFilesQuiet(
     path.join(templateDir, '.claude', 'commands'),
     path.join(targetDir, '.claude', 'commands'),
@@ -259,8 +235,8 @@ function install(targetDir) {
   );
   fileLog(SYM.check, `${cmds.length} 个命令 — ${DIM}/phase /status /checkpoint /review${RESET}`);
 
-  // Step 6: settings.json
-  step(6, STEPS, '配置 Hooks');
+  // Step 7: settings.json
+  step(7, STEPS, '配置 Hooks');
   const targetSettings = path.join(targetDir, '.claude', 'settings.json');
   const sourceSettings = path.join(templateDir, '.claude', 'settings.json');
 
@@ -284,11 +260,12 @@ function install(targetDir) {
   resultBanner('安装完成');
 
   // 文件树
-  console.log(`  ${DIM}已安装 ${rules.length + hookCount + cmds.length + 2} 个文件：${RESET}`);
+  console.log(`  ${DIM}已安装 ${rules.length + hookCount + cmds.length + 3} 个文件：${RESET}`);
   blank();
   console.log(`  ${BOLD}${path.basename(targetDir)}/${RESET}`);
-  console.log(`  ${SYM.tee} CLAUDE.md              ${DIM}核心控制文件${RESET}`);
+  console.log(`  ${SYM.tee} CLAUDE.md              ${DIM}核心控制文件（升级时自动更新）${RESET}`);
   console.log(`  ${SYM.corner} ${BOLD}.claude/${RESET}`);
+  console.log(`     ${SYM.tee} project-state.md    ${DIM}项目状态（升级时保留）${RESET}`);
   console.log(`     ${SYM.tee} settings.json       ${DIM}Hooks 配置${RESET}`);
   console.log(`     ${SYM.tee} ${BOLD}rules/${RESET}              ${DIM}${rules.length} 个规则 (自动加载)${RESET}`);
   console.log(`     ${SYM.tee} ${BOLD}hooks/${RESET}              ${DIM}${hookCount} 个拦截脚本${RESET}`);
@@ -329,29 +306,37 @@ function uninstall(targetDir) {
   console.log(`  ${SYM.arrow} 目标  ${BOLD}${targetDir}${RESET}`);
   blank();
 
-  const removed = [];
+  let removed = 0;
 
   // CLAUDE.md
   const claudeMd = path.join(targetDir, 'CLAUDE.md');
   if (fs.existsSync(claudeMd)) {
     fs.unlinkSync(claudeMd);
-    removed.push('CLAUDE.md');
+    removed++;
     fileLog(SYM.check, `${DIM}删除${RESET} CLAUDE.md`);
   }
 
-  // .claude 子目录
+  // project-state.md
+  const stateMd = path.join(targetDir, '.claude', 'project-state.md');
+  if (fs.existsSync(stateMd)) {
+    fs.unlinkSync(stateMd);
+    removed++;
+    fileLog(SYM.check, `${DIM}删除${RESET} .claude/project-state.md`);
+  }
+
+  // .claude 子目录（全部删除）
   const removeDirs = ['rules', 'hooks', 'commands', 'reviews'];
   for (const dir of removeDirs) {
     const dirPath = path.join(targetDir, '.claude', dir);
     if (fs.existsSync(dirPath)) {
       const count = fs.readdirSync(dirPath).length;
       fs.rmSync(dirPath, { recursive: true });
-      removed.push(`.claude/${dir}/`);
+      removed++;
       fileLog(SYM.check, `${DIM}删除${RESET} .claude/${dir}/ ${DIM}(${count} 个文件)${RESET}`);
     }
   }
 
-  // settings.json
+  // settings.json — 仅清理 SDLC hooks，保留用户其他配置
   const settingsPath = path.join(targetDir, '.claude', 'settings.json');
   if (fs.existsSync(settingsPath)) {
     try {
@@ -364,16 +349,16 @@ function uninstall(targetDir) {
       }
       if (Object.keys(settings).length === 0) {
         fs.unlinkSync(settingsPath);
-        removed.push('settings.json');
+        removed++;
         fileLog(SYM.check, `${DIM}删除${RESET} .claude/settings.json`);
       } else {
         fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-        removed.push('settings.json (hooks)');
+        removed++;
         fileLog(SYM.check, `${DIM}清理${RESET} settings.json ${DIM}(仅移除 hooks，保留其他配置)${RESET}`);
       }
     } catch (_) {
       fs.unlinkSync(settingsPath);
-      removed.push('settings.json');
+      removed++;
       fileLog(SYM.check, `${DIM}删除${RESET} .claude/settings.json`);
     }
   }
@@ -388,8 +373,8 @@ function uninstall(targetDir) {
     }
   }
 
-  if (removed.length > 0) {
-    resultBanner(`卸载完成 — 已清理 ${removed.length} 项`);
+  if (removed > 0) {
+    resultBanner(`卸载完成 — 已清理 ${removed} 项`);
     console.log(`  ${DIM}重新安装：npx claude-sdlc${RESET}`);
   } else {
     blank();
@@ -398,4 +383,4 @@ function uninstall(targetDir) {
   blank();
 }
 
-module.exports = { install, uninstall, mergeSettings, extractYamlState, hasActiveState, mergeClaudeMd };
+module.exports = { install, uninstall, mergeSettings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-sdlc",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "让 Claude Code 严格按 SDLC 规范开发 — 一条命令安装",
   "bin": {
     "claude-sdlc": "./bin/cli.js"

package/template/.claude/commands/checkpoint.md

@@ -9,8 +9,8 @@
 ## 执行逻辑
 
 1. **收集当前状态信息**：
-   - 读取 CLAUDE.md 中的 `current_phase`
-   - 读取 CLAUDE.md 中的 `task_description`
+   - 读取 .claude/project-state.md 中的 `current_phase`
+   - 读取 .claude/project-state.md 中的 `task_description`
    - 执行 `git status`（如果是 git 仓库）获取文件变更状态
    - 执行 `git diff --stat`（如果是 git 仓库）获取变更统计
 
@@ -36,7 +36,7 @@
    ========================
    ```
 
-3. **更新 CLAUDE.md**：
+3. **更新 .claude/project-state.md**：
    - 确保 `modified_files` 列表是最新的
    - 确保 `todo_items` 列表是最新的
    - 更新 `last_updated` 时间戳
@@ -46,7 +46,7 @@
    ```
    ✅ 检查点已保存。
 
-   如果后续发生上下文压缩（compaction），可以从 CLAUDE.md 恢复以下状态：
+   如果后续发生上下文压缩（compaction），可以从 .claude/project-state.md 恢复以下状态：
    - 阶段：{阶段}
    - 任务：{任务描述}
    - 已修改 {n} 个文件

package/template/.claude/commands/phase.md

@@ -11,7 +11,7 @@
 根据参数执行以下操作：
 
 ### 无参数 或 `status`
-1. 读取 CLAUDE.md 中的 `current_phase` 值
+1. 读取 .claude/project-state.md 中的 `current_phase` 值
 2. 输出当前阶段信息：
    - 阶段编号和名称
    - 该阶段允许的操作
@@ -52,9 +52,9 @@ Step 3: 审查通过？
    - 自动执行当前阶段对应的 `/review`
    - 输出审查报告
 5. **审查通过**：
-   - 将 `current_phase` 更新为下一阶段
-   - 更新 `phase_history` 记录（含审查结果摘要）
-   - 更新 `last_updated` 时间戳
+   - 将 .claude/project-state.md 的 `current_phase` 更新为下一阶段
+   - 更新 .claude/project-state.md 的 `phase_history` 记录（含审查结果摘要）
+   - 更新 .claude/project-state.md 的 `last_updated` 时间戳
    - **P1→P2、P2→P3**：输出新阶段的入口信息（P2→P3 时提示"进入自动驱动模式"）
    - **P3→P4、P4→P5、P5→P6**：不输出冗余信息，立即开始下一阶段工作
    - **P6 完成**：输出交付摘要报告
@@ -67,9 +67,9 @@ Step 3: 审查通过？
 1. 读取当前阶段
 2. 如果已是 P0/P1，提示无法继续回退
 3. 要求提供回退原因
-4. 更新 `current_phase` 为上一阶段
-5. 更新 `phase_history` 记录（含回退原因）
-6. 更新 `last_updated` 时间戳
+4. 更新 .claude/project-state.md 的 `current_phase` 为上一阶段
+5. 更新 .claude/project-state.md 的 `phase_history` 记录（含回退原因）
+6. 更新 .claude/project-state.md 的 `last_updated` 时间戳
 7. 输出回退后的阶段信息
 8. 注意：回退后上一阶段的审查状态重置，再次推进时需重新审查
 

package/template/.claude/commands/review.md

@@ -35,7 +35,7 @@
 
 ### 1. 自动识别当前阶段
 
-读取 CLAUDE.md 中的 `current_phase`，根据阶段选择对应的审查清单。
+读取 .claude/project-state.md 中的 `current_phase`，根据阶段选择对应的审查清单。
 
 ### 2. 确定审查范围
 
@@ -57,7 +57,7 @@
 - [ ] **影响分析**：受影响的文件和模块是否已识别完整
 - [ ] **风险识别**：技术风险和业务风险是否已列出
 - [ ] **用户已确认**：PRD 是否已经用户明确确认
-- [ ] **已写入 CLAUDE.md**：PRD 是否已写入 `prd` 字段
+- [ ] **已写入 .claude/project-state.md**：PRD 是否已写入 `prd` 字段
 
 ### 输出格式
 ```
@@ -141,7 +141,7 @@
 ## P3 编码实现 — 代码审查
 
 ### 审查范围
-- 审查 CLAUDE.md 中 `modified_files` 列表里的所有文件
+- 审查 .claude/project-state.md 中 `modified_files` 列表里的所有文件
 - 如指定了文件路径，仅审查该文件
 
 ### 工具执行（P3 审查前必须运行）

package/template/.claude/commands/status.md

@@ -10,7 +10,7 @@
 
 执行深度自检并生成全面的项目状态报告：
 
-### 1. 读取 CLAUDE.md 状态
+### 1. 读取 .claude/project-state.md 状态
 - `current_phase` — 当前阶段
 - `task_description` — 任务描述
 - `started_at` / `last_updated` — 时间信息
@@ -74,7 +74,7 @@
 ```
 
 ### 4. 同步更新
-- 如果发现 CLAUDE.md 中的信息不是最新，同步更新
+- 如果发现 .claude/project-state.md 中的信息不是最新，同步更新
 - 更新 `last_updated` 时间戳
 
 ---

package/template/.claude/hooks/check-phase-test.sh

@@ -22,30 +22,18 @@ if [ -z "$COMMAND" ]; then
 fi
 
 # ==============================
-# 查找 CLAUDE.md 并读取阶段
+# 读取项目状态
 # ==============================
 
-find_claude_md() {
-  local dir="$PWD"
-  while [ "$dir" != "/" ]; do
-    if [ -f "$dir/CLAUDE.md" ]; then
-      echo "$dir/CLAUDE.md"
-      return 0
-    fi
-    dir=$(dirname "$dir")
-  done
-  return 1
-}
-
-CLAUDE_MD=$(find_claude_md 2>/dev/null) || true
-
-# 如果找不到 CLAUDE.md，默认放行（容错）
-if [ -z "$CLAUDE_MD" ]; then
+STATE_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/project-state.md"
+
+# 如果找不到状态文件，默认放行（容错）
+if [ ! -f "$STATE_FILE" ]; then
   exit 0
 fi
 
 # 读取当前阶段 — 兼容 macOS（不使用 grep -oP）
-CURRENT_PHASE=$(sed -n 's/^current_phase:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$CLAUDE_MD" 2>/dev/null | head -1)
+CURRENT_PHASE=$(sed -n 's/^current_phase:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$STATE_FILE" 2>/dev/null | head -1)
 
 if [ -z "$CURRENT_PHASE" ]; then
   exit 0

package/template/.claude/hooks/check-phase-write.sh

@@ -23,43 +23,29 @@ if [ -z "$FILE_PATH" ]; then
 fi
 
 # 文档/配置类文件扩展名 — 任何阶段都允许写入
-# 注意：.html 和 .css 是代码文件（Web 项目），不在白名单中
 DOC_EXTENSIONS='\.(md|txt|json|yaml|yml|toml|ini|cfg|conf|gitignore|editorconfig|prettierrc|eslintrc|csv|xml|svg|lock|log|env|env\..*)$'
 
 if echo "$FILE_PATH" | grep -qiE "$DOC_EXTENSIONS"; then
   exit 0
 fi
 
-# 查找项目根目录的 CLAUDE.md
-find_claude_md() {
-  local dir="$PWD"
-  while [ "$dir" != "/" ]; do
-    if [ -f "$dir/CLAUDE.md" ]; then
-      echo "$dir/CLAUDE.md"
-      return 0
-    fi
-    dir=$(dirname "$dir")
-  done
-  return 1
-}
-
-CLAUDE_MD=$(find_claude_md 2>/dev/null) || true
-
-# 如果找不到 CLAUDE.md，默认放行（容错）
-if [ -z "$CLAUDE_MD" ]; then
+# 读取项目状态文件
+STATE_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/project-state.md"
+
+# 如果找不到状态文件，默认放行（容错）
+if [ ! -f "$STATE_FILE" ]; then
   exit 0
 fi
 
-# 读取当前阶段 — 兼容 macOS (BSD grep) 和 Linux (GNU grep)
-# 不使用 grep -oP（macOS 不支持 Perl 正则）
-CURRENT_PHASE=$(sed -n 's/^current_phase:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$CLAUDE_MD" 2>/dev/null | head -1)
+# 读取当前阶段 — 兼容 macOS (BSD sed)
+CURRENT_PHASE=$(sed -n 's/^current_phase:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$STATE_FILE" 2>/dev/null | head -1)
 
 # 如果无法确定阶段，默认放行（容错）
 if [ -z "$CURRENT_PHASE" ]; then
   exit 0
 fi
 
-# 提取阶段编号（P0→0, P1→1, ...）— 兼容 macOS
+# 提取阶段编号（P0→0, P1→1, ...）
 PHASE_NUM=$(echo "$CURRENT_PHASE" | sed 's/[^0-9]//g' 2>/dev/null)
 
 if [ -z "$PHASE_NUM" ]; then

package/template/.claude/project-state.md

@@ -0,0 +1,42 @@
+# SDLC 项目状态（活文档 — 持续更新）
+
+> **COMPACTION 保护区域：压缩时必须保留。每次变更后立即更新。**
+> 本文件是项目状态唯一存储位置，通过 CLAUDE.md 的 @import 自动加载。
+> 升级 claude-sdlc 时本文件不会被覆盖。
+
+```yaml
+# === SDLC 项目状态 ===
+current_phase: P0  # P0=未开始, P1=需求, P2=设计, P3=编码, P4=测试, P5=审查, P6=部署
+task_description: ""
+started_at: ""
+last_updated: ""
+
+# PRD — 用户确认的需求清单（P1 产出，P2-P6 唯一依据）
+prd:
+  # - id: R1
+  #   description: "需求描述"
+  #   acceptance_criteria: "验收标准"
+
+architecture_decisions: []
+modified_files: []
+todo_items: []
+review_retry_count: 0  # 自动驱动审查重试计数，阶段推进后重置
+phase_history: []
+key_context: ""  # compaction 后恢复用
+```
+
+### 状态更新时机
+
+| 事件 | 更新字段 |
+|------|---------|
+| 新任务 | `current_phase`→P1, `task_description`, `started_at` |
+| PRD 确认 | `prd`（编号化需求列表，此后为唯一依据） |
+| 阶段推进 | `current_phase`, `phase_history`, `review_retry_count`→0, `last_updated` |
+| 文件修改 | `modified_files`（追加路径）, `last_updated` |
+| 架构决策 | `architecture_decisions`, `last_updated` |
+| 审查重试 | `review_retry_count`+1, `last_updated` |
+| 即将压缩 | 所有字段确认最新, `key_context`（写入当前工作摘要） |
+
+# Compact Instructions
+
+压缩时必须保留：(1) 本文件路径和存在性 (2) 上方 YAML 块完整内容 (3) 当前阶段和任务 (4) 已修改文件列表 (5) 架构决策 (6) 用户最近指令。恢复后：P1/P2 等待用户确认继续，P3-P6 自动恢复自动驱动继续完成。

package/template/.claude/rules/01-lifecycle-phases.md

@@ -33,7 +33,7 @@
 
 ### PRD 确认流程
 1. Claude 整理 PRD 初稿后，**必须向用户展示完整的需求清单**
-2. 用户确认后，将 PRD 写入 CLAUDE.md 的 `prd` 字段
+2. 用户确认后，将 PRD 写入 .claude/project-state.md 的 `prd` 字段
 3. **PRD 一旦写入即锁定**，后续阶段以此为唯一依据
 4. 如需修改 PRD，必须回到 P1 重新获得用户确认
 
@@ -46,11 +46,11 @@
 - [ ] 技术可行性 — 在当前技术栈下可实现
 - [ ] 影响分析 — 受影响的文件和模块已识别
 - [ ] **用户已确认** — PRD 经用户明确确认
-- [ ] **PRD 已写入 CLAUDE.md** — `prd` 字段已填写
+- [ ] **PRD 已写入 .claude/project-state.md** — `prd` 字段已填写
 
 ### 退出条件
 - PRD 已整理完成并经用户确认
-- PRD 已写入 CLAUDE.md 的 `prd` 字段
+- PRD 已写入 .claude/project-state.md 的 `prd` 字段
 - 影响范围已明确
 - **需求审查已通过**（`/review`）
 
@@ -69,7 +69,7 @@
 
 ### 入口条件
 - P1 需求分析已完成（含需求审查通过）
-- PRD 已获用户确认并写入 CLAUDE.md
+- PRD 已获用户确认并写入 .claude/project-state.md
 
 ### 阶段活动
 - **【最新技术与设计调研 — 必须首先执行】**：
@@ -145,7 +145,7 @@
   3. 确保使用当前推荐的 API，不使用已废弃（deprecated）的方法或过时写法
 - **严格按 P2 设计方案编写代码，不添加 PRD 之外的功能**
 - 遵循编码规范（见 02-coding-standards.md）
-- 每完成一个逻辑单元，更新 CLAUDE.md 中的 modified_files
+- 每完成一个逻辑单元，更新 .claude/project-state.md 中的 modified_files
 - 记录实现中的关键决策
 - **如发现 PRD 有遗漏或设计需调整，停止编码，回退到 P1/P2 与用户确认**
 - **多 Agent 并行编码**（如有独立模块）：按设计方案拆分独立模块，用 Task 工具并行派发子 Agent 编码（见 07-parallel-agents.md）
@@ -159,7 +159,7 @@
 ### 必需产出物
 - [ ] 功能代码实现（**仅限 PRD 范围**）
 - [ ] 代码符合编码规范
-- [ ] CLAUDE.md 中 modified_files 已更新
+- [ ] .claude/project-state.md 中 modified_files 已更新
 - [ ] 关键实现决策已记录
 
 ### 阶段审查（代码审查）

package/template/.claude/rules/05-anti-amnesia.md

@@ -10,9 +10,9 @@ Claude Code 存在以下可能导致规范失效的场景：
 
 | 场景 | 风险 | 防御机制 |
 |------|------|---------|
-| 新会话启动 | Claude 不知道有规范 | CLAUDE.md + rules/ 自动加载 |
+| 新会话启动 | Claude 不知道有规范 | CLAUDE.md + rules/ + project-state.md 自动加载 |
 | 长对话漂移 | Claude 渐渐忘记规范 | Stop hook 每次回复后强制自检 |
-| Context Compaction | 早期对话被压缩丢弃 | PreCompact hook 保存状态 → CLAUDE.md 重新加载恢复 |
+| Context Compaction | 早期对话被压缩丢弃 | PreCompact hook 保存状态 → .claude/project-state.md 重新加载恢复 |
 | 用户催促跳过 | Claude 放弃规范直接执行 | Hooks 硬拦截违规操作 |
 | 新任务覆盖 | 上一任务状态残留 | 新任务检测 → 自动重置 |
 | Claude 自行判断不需要 | Claude 认为简单任务不需要走流程 | CLAUDE.md 明确"所有开发任务必须" |
@@ -23,6 +23,7 @@ Claude Code 存在以下可能导致规范失效的场景：
 
 ### 第一层：CLAUDE.md 启动指令（主动）
 - CLAUDE.md 在每次会话开始和 compaction 后自动加载
+- CLAUDE.md 通过 @import 引用 `.claude/project-state.md`，项目状态存储在该文件中
 - **「启动指令」要求 Claude 读到该文件时立即执行状态检查**
 - 这确保 Claude 不是被动接收规范，而是主动执行初始化
 - **这是最关键的防线**
@@ -42,20 +43,20 @@ Claude Code 存在以下可能导致规范失效的场景：
 - 这是**不依赖 Claude 自觉性的被动安全网**
 
 ### 第四层：PostToolUse Hook — 状态同步（主动）
-- 每次 Write/Edit 操作后，prompt hook 提醒 Claude 更新 CLAUDE.md
-- 确保 modified_files 列表实时最新
+- 每次 Write/Edit 操作后，prompt hook 提醒 Claude 更新 .claude/project-state.md
+- 确保 modified_files 列表实时最新（状态存储在 .claude/project-state.md 中）
 - 为 compaction 后的恢复提供准确的文件清单
 
 ### 第五层：Stop Hook — 回复后审查（主动）
 - 每次回复完成后触发
-- **强制 Claude 用 Read 工具重新读取 CLAUDE.md**，而非依赖记忆
+- **强制 Claude 用 Read 工具重新读取 .claude/project-state.md**，而非依赖记忆
 - 检查阶段合规性、状态最新性
 - 发现偏离时立即纠正
 
 ### 第六层：PreCompact Hook — 压缩前保存（主动）
 - **prompt 类型**，直接指令 Claude 在压缩前保存所有状态
-- 要求 Claude 用 Read 读取 CLAUDE.md 确认状态，用 Edit 更新缺失信息
-- 特别要求写入 key_context 摘要，确保恢复时有足够上下文
+- 要求 Claude 用 Read 读取 .claude/project-state.md 确认状态，用 Edit 更新缺失信息
+- 特别要求写入 key_context 摘要到 .claude/project-state.md，确保恢复时有足够上下文
 
 ### 第七层：用户命令（按需）
 - `/status` — 随时查看完整状态，触发深度自检
@@ -73,7 +74,7 @@ Claude Code 存在以下可能导致规范失效的场景：
 1. Claude Code 启动 → 自动加载 CLAUDE.md + rules/
 2. CLAUDE.md「启动指令」执行 → 检查 current_phase = P0
 3. Claude 识别到"实现"是开发请求 → 自动进入 P1
-4. 更新 CLAUDE.md: current_phase=P1, task_description="实现登录功能"
+4. 更新 .claude/project-state.md: current_phase=P1, task_description="实现登录功能"
 5. 开始需求分析 → 整理 PRD → 向用户展示 PRD 等待确认
 6. 用户确认 PRD → 自动审查 → 进入 P2 → 设计方案 → 向用户展示等待确认
 7. 用户确认设计 → 自动审查 → 进入自动驱动模式
@@ -85,7 +86,7 @@ Claude Code 存在以下可能导致规范失效的场景：
 
 ```
 1. 当前在 P3 自动驱动中
-2. PreCompact hook 触发 → Claude 被指令保存状态到 CLAUDE.md
+2. PreCompact hook 触发 → Claude 被指令保存状态到 .claude/project-state.md
 3. Compaction 执行 → 对话历史被压缩
 4. CLAUDE.md 重新加载 → 「启动指令」重新执行
 5. Claude 读取 current_phase=P3 → 知道正在自动驱动的编码阶段
@@ -98,7 +99,7 @@ Claude Code 存在以下可能导致规范失效的场景：
 ```
 1. Claude 调用 Write 工具写 .py 文件
 2. PreToolUse hook (check-phase-write.sh) 执行
-3. 读取 CLAUDE.md: current_phase=P1
+3. 读取 .claude/project-state.md: current_phase=P1
 4. P1 < P3 → 输出拦截信息，exit 2
 5. Claude 收到拦截信息 → 向用户说明不能在 P1 写代码
 6. 继续需求分析工作
@@ -153,13 +154,13 @@ Claude Code 存在以下可能导致规范失效的场景：
 **每次回复前执行（内部 4 步）：**
 
 ```
-1. 【阶段】我当前在哪个阶段？→ 检查 CLAUDE.md 的 current_phase
+1. 【阶段】我当前在哪个阶段？→ 检查 .claude/project-state.md 的 current_phase
 2. 【PRD】我接下来要做的事，对应 PRD 中的哪条需求？→ 如果对应不上，不做
 3. 【合规】我要执行的操作在当前阶段允许吗？→ 对照允许列表
-4. 【状态】CLAUDE.md 的状态是最新的吗？→ 如有变更需更新
+4. 【状态】.claude/project-state.md 的状态是最新的吗？→ 如有变更需更新
 ```
 
-**疑问时的行为：不猜测，用 Read 工具重新读取 CLAUDE.md。**
+**疑问时的行为：不猜测，用 Read 工具重新读取 .claude/project-state.md。**
 
 ---
 
@@ -173,7 +174,7 @@ Claude Code 存在以下可能导致规范失效的场景：
 - Stop hook 提醒时
 
 ```
-1. 用 Read 工具读取 CLAUDE.md「当前项目状态」YAML
+1. 用 Read 工具读取 .claude/project-state.md 的 YAML 状态
 2. 确认 current_phase 值
 3. 确认 task_description 值
 4. 回顾 modified_files 列表 — 是否有遗漏
@@ -188,7 +189,7 @@ Claude Code 存在以下可能导致规范失效的场景：
 ## 6. 异常恢复流程
 
 ### 自动恢复（优先）
-1. 用 Read 工具读取 CLAUDE.md 获取最新状态
+1. 用 Read 工具读取 .claude/project-state.md 获取最新状态
 2. 根据 modified_files 列表，用 Read 工具读取已修改的文件以恢复上下文
 3. 向用户报告恢复结果
 

package/template/.claude/settings.json

@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '{\"decision\":\"block\",\"reason\":\"SDLC: File modified. Use Edit to update CLAUDE.md: append the modified file path to modified_files (if not already listed) and update last_updated. This is mandatory, do not skip.\"}'"
+            "command": "echo '{\"decision\":\"block\",\"reason\":\"SDLC: File modified. Use Edit to update .claude/project-state.md: append the modified file path to modified_files (if not already listed) and update last_updated. This is mandatory, do not skip.\"}'"
           }
         ]
       }
@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nIMPORTANT: First check if stop_hook_active is true in the context above. If it is true, respond immediately with {\"ok\": true} to prevent infinite loops.\n\nOtherwise, check the conversation transcript and determine:\n1. Is there an active SDLC phase (P1-P6) with remaining work?\n2. For P3/P4/P5 auto-drive phases: has the /review been executed and passed?\n3. Are there uncompleted PRD requirements?\n4. Has CLAUDE.md YAML state been updated after the latest changes?\n\nRespond with JSON: {\"ok\": true} if all tasks are complete and Claude can stop, or {\"ok\": false, \"reason\": \"SDLC self-check: [describe what still needs to be done, e.g. run /review, update CLAUDE.md YAML, continue to next phase, etc.]\"} if Claude should continue working.",
+            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nIMPORTANT: First check if stop_hook_active is true in the context above. If it is true, respond immediately with {\"ok\": true} to prevent infinite loops.\n\nOtherwise, check the conversation transcript and determine:\n1. Is there an active SDLC phase (P1-P6) with remaining work?\n2. For P3/P4/P5 auto-drive phases: has the /review been executed and passed?\n3. Are there uncompleted PRD requirements?\n4. Has .claude/project-state.md YAML state been updated after the latest changes?\n\nRespond with JSON: {\"ok\": true} if all tasks are complete and Claude can stop, or {\"ok\": false, \"reason\": \"SDLC self-check: [describe what still needs to be done, e.g. run /review, update .claude/project-state.md YAML, continue to next phase, etc.]\"} if Claude should continue working.",
             "timeout": 30
           }
         ]
@@ -48,7 +48,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "You are evaluating a conversation before context compaction. Context: $ARGUMENTS\n\nCheck if CLAUDE.md YAML state block has been updated with latest values for: current_phase, task_description, prd, modified_files, architecture_decisions, todo_items, key_context.\n\nRespond with JSON: {\"ok\": true} if state is saved, or {\"ok\": false, \"reason\": \"Before compaction: update CLAUDE.md YAML - save current_phase, task_description, modified_files, and write key_context summary of current work and next steps.\"}",
+            "prompt": "You are evaluating a conversation before context compaction. Context: $ARGUMENTS\n\nCheck if .claude/project-state.md YAML state block has been updated with latest values for: current_phase, task_description, prd, modified_files, architecture_decisions, todo_items, key_context.\n\nRespond with JSON: {\"ok\": true} if state is saved, or {\"ok\": false, \"reason\": \"Before compaction: update .claude/project-state.md YAML - save current_phase, task_description, modified_files, and write key_context summary of current work and next steps.\"}",
             "timeout": 30
           }
         ]

package/template/CLAUDE.md

@@ -2,9 +2,11 @@
 
 > 详细规则见 `.claude/rules/`（自动加载）。可用命令：`/phase`、`/status`、`/checkpoint`、`/review`。
 
+@.claude/project-state.md
+
 ## 启动指令（加载时立即执行）
 
-1. 读取下方 `current_phase` 值
+1. 用 Read 工具读取 `.claude/project-state.md` 获取 `current_phase` 值
 2. **P1-P6**：向用户简要报告状态（阶段、任务、已修改文件数），继续工作
 3. **P0 或空**：等待用户提出任务
 4. 所有后续操作遵守 SDLC 规范
@@ -66,52 +68,9 @@ P3/P4/P5 阶段有独立模块时，用 Task 工具并行派发子 Agent 提高
 
 ### 每次回复前 4 步自检
 
-1. **阶段** — `current_phase` 是什么？
+1. **阶段** — `current_phase` 是什么？（读 `.claude/project-state.md`）
 2. **PRD** — 要做的事对应 PRD 哪条？对应不上则不做
 3. **合规** — 操作在当前阶段允许吗？
-4. **状态** — 变更后 YAML 更新了吗？
-
-有疑问 → 用 Read 重读本文件，不依赖记忆。详见 `.claude/rules/05-anti-amnesia.md`。
-
----
-
-## 当前项目状态（活文档 — 持续更新）
-
-> **COMPACTION 保护区域：压缩时必须保留。每次变更后立即更新。**
-
-```yaml
-# === SDLC 项目状态 ===
-current_phase: P0  # P0=未开始, P1=需求, P2=设计, P3=编码, P4=测试, P5=审查, P6=部署
-task_description: ""
-started_at: ""
-last_updated: ""
-
-# PRD — 用户确认的需求清单（P1 产出，P2-P6 唯一依据）
-prd:
-  # - id: R1
-  #   description: "需求描述"
-  #   acceptance_criteria: "验收标准"
-
-architecture_decisions: []
-modified_files: []
-todo_items: []
-review_retry_count: 0  # 自动驱动审查重试计数，阶段推进后重置
-phase_history: []
-key_context: ""  # compaction 后恢复用
-```
-
-### 状态更新时机
-
-| 事件 | 更新字段 |
-|------|---------|
-| 新任务 | `current_phase`→P1, `task_description`, `started_at` |
-| PRD 确认 | `prd`（编号化需求列表，此后为唯一依据） |
-| 阶段推进 | `current_phase`, `phase_history`, `review_retry_count`→0, `last_updated` |
-| 文件修改 | `modified_files`（追加路径）, `last_updated` |
-| 架构决策 | `architecture_decisions`, `last_updated` |
-| 审查重试 | `review_retry_count`+1, `last_updated` |
-| 即将压缩 | 所有字段确认最新, `key_context`（写入当前工作摘要） |
-
-# Compact Instructions
+4. **状态** — 变更后 `.claude/project-state.md` 更新了吗？
 
-压缩时必须保留：(1) 本文件路径和存在性 (2) 上方 YAML 块完整内容 (3) 当前阶段和任务 (4) 已修改文件列表 (5) 架构决策 (6) 用户最近指令。恢复后：P1/P2 等待用户确认继续，P3-P6 自动恢复自动驱动继续完成。
+有疑问 → 用 Read 重读 `.claude/project-state.md`，不依赖记忆。详见 `.claude/rules/05-anti-amnesia.md`。