claude init inited

2026-04-24 16:42:22 +08:00
commit 4c9f4f250d
39 changed files with 3185 additions and 0 deletions
--- a/.claude/skills/claude-init/SKILL.md
+++ b/.claude/skills/claude-init/SKILL.md
@@ -0,0 +1,844 @@
+---
+name: claude-init
+description: Initializes the .claude structure for a new project. Two trigger paths - (1) auto on first session when .claude/.init-done is missing, (2) manual via keywords like "初始化claude", "claude init", "重置 claude", "补 gitignore". Identifies and relocates target project's original rules/skills, cleans template residue (changelog/deferred/pitfalls/profile/distillery/local settings/project-level rules and skills), optionally generates .gitignore, and writes .claude/.init-done sentinel on completion. Already-initialized repos skip auto-trigger unless user invokes keywords.
+---
+
+# Claude Init Skill
+
+把从其它项目复制过来（或通过 git clone 模板仓库获得）的 `.claude/` 目录重置为当前新项目的干净起点。
+
+## 使用场景
+
+### 场景 A：克隆模板仓库后的首次会话
+
+```
+1. 用户把本模板作为 git 仓库发布
+2. 其他人 `git clone <模板仓库>` 得到新项目骨架
+3. 用户打开 Claude Code，在该仓库发出任意第一条消息
+4. `claude-init-recall.md`（alwaysApply）检测 .claude/.init-done 不存在
+   → 引导 Agent 暂停用户原始请求，先执行本 Skill
+5. Agent 按阶段 0 → 7 跑完，写入 .init-done
+6. 后续会话 sentinel 已存在，不再自动触发
+```
+
+### 场景 B：从已有项目直接复制 .claude 目录
+
+```
+1. 用户在 "源项目 A" 中使用本 .claude 模板开发
+2. 用户开 "新项目 B"，把 A 的 .claude/ 整体拷贝到 B
+3. B 原先可能也有自己零散的 rules/SKILL 文件（未必标准）
+4. 用户在 B 中说"初始化claude"（或首次会话被 recall 触发）
+5. 本 Skill 把 B 原有的 rules/skills 按 baserule 归位，清空 A 遗留的项目数据，
+   生成 .gitignore，写入 sentinel
+```
+
+### 场景 C：只补 .gitignore
+
+```
+init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
+```
+
+## 触发条件
+
+本 Skill 由 `claude-init-recall.md` 触发，两类入口：
+
+### A. 全流程（阶段 0 → 7）
+
+- `.claude/.init-done` 不存在 → 会话首次响应前由 recall 规则自动引导
+- 用户关键词：`初始化claude` / `claude init` / `重置 claude` / `reset claude` 等
+- 口头描述"把复制过来的 .claude 清理一下"、"按 baserule 归位一下"
+
+### B. 仅补 .gitignore（只跑阶段 5.5）
+
+- 用户关键词：`补 gitignore` / `生成 gitignore` / `gitignore 模板`
+- 跳过阶段 1-5 和阶段 7 的除"更新 gitignore_generated 字段"外的其他操作
+
+## 执行原则（不可协商）
+
+1. **稳定准确 > token 成本**：每一步可以多读、多确认、让用户点头，不要图快
+2. **破坏性操作必须 dry-run**：删除、重置必须先列清单给用户确认
+3. **不可逆操作前提醒 git**：开始前先提示用户确认工作区已 commit/stash
+4. **模糊就问**：分类不清的文件一律问用户，不要猜
+5. **幂等**：反复运行应当无害（第二次在已干净状态下不会做破坏）
+6. **中断可恢复**：任何阶段异常 abort **不写入** `.init-done`，下次会话仍会被 recall 触发从头继续
+
+## 核心流程
+
+### 阶段 0：前置确认 + 幂等判断
+
+```
+1. 检查当前工作目录下存在 .claude/
+   - 不存在 → 直接结束，提示用户先复制模板
+2. 读取 .claude/.init-done
+   - 不存在 → 继续，按"首次 init"路径执行
+   - 已存在 → 展示其元数据（initialized_at、project_type 等），提示：
+     "检测到本仓库已于 {initialized_at} 完成初始化（project_type: {type}）。
+      继续执行会清空 changelog / deferred / pitfalls / distillery 等数据文件。确认要继续吗？"
+     等用户明确回复"继续"再往下
+3. 运行 `git status`：
+   - 不是 git 仓库 → 警告但不阻塞，建议手动备份
+   - 有未提交改动 → 提醒"建议先 commit 或 stash，便于回滚"，等用户明确回复"继续"
+4. 向用户声明本次操作范围（见"分组规则"），请求口头确认启动
+```
+
+### 阶段 1：递归扫描 `.claude/`
+
+```
+1. 用 shell 列出 .claude 下所有文件（含子目录）
+2. 把每个文件对照"规范清单"和"清理清单"分成三组：
+   - A 组（canonical）：在规范清单中，原样保留
+   - B 组（template-data）：在清理清单中，需要删除或重置
+   - C 组（foreign）：两张清单都没覆盖到的，视作目标项目原有文件或未知项
+3. 把分组结果用表格汇报给用户：
+   | 组 | 路径 | 处理动作 |
+```
+
+### 阶段 2：处理 C 组（目标项目原有文件归位）
+
+对 C 组中的每个文件，按 baserule.md 的归属约定分类，逐条询问用户（可一次性列清单批量确认）：
+
+| 文件特征 | 建议归属 | 目标路径 |
+|----------|----------|----------|
+| `.md`/`.mdc` 且内容是跨项目通用规则 | 通用 Rule | `.claude/rules/common/<name>.md` + CLAUDE.md 追加 @import |
+| `.md`/`.mdc` 且内容是当前新项目专属规则 | 项目 Rule | `.claude/rules/project/<name>.md` + CLAUDE.md 追加 @import |
+| 包含 `SKILL.md` 的目录 | Skill（无论通用/项目专属） | `.claude/skills/<skill-name>/` |
+| 看不出归属 | 询问用户 | — |
+| 明显是临时/垃圾文件（`*.log`、`*.tmp`、缓存等） | 删除（需用户确认） | — |
+
+执行要点：
+
+- **先列清单一次性确认**，然后批量执行移动/删除，避免交互过于频繁
+- **重名冲突**：C 组文件若与 A 组规范文件重名，**保留 A 组版本**，把 C 组备份到 `.claude/_init-backup/` 下让用户自行 diff，不直接覆盖
+- **Skill 归属提示**：通用 Skill 建议用户之后手动同步到 `~/.claude/skills/`（跨项目便利副本，可选）
+- **迁移后核查**：移动完成后重新扫描，确认 C 组已清空
+- **CLAUDE.md 同步**：任何移到 `rules/common/` 或 `rules/project/` 的 rule 文件都必须在 `CLAUDE.md` 对应段追加 `@import` 语句
+
+### 阶段 3：处理 B 组（源项目项目专用数据清理/重置）
+
+按"清理清单"执行：
+
+**A. 直接删除**
+
+- `.claude/rules/project/*.md`（全部）—— 源项目的项目级 rules，新项目不适用。**同时清理 `CLAUDE.md` 中对应的 `@rules/project/...` 引用行**
+- `.claude/skills/<非规范 skill 目录>/` —— 源项目的项目级 Skills（不在白名单的所有 skill 目录）
+- `.claude/plans/` 下所有文件（目录保留，内容清空；若目录不存在则跳过）
+- `.claude/debug-*.log`、`.claude/*.log` —— 调试日志
+- `.claude/settings.local.json` —— 设备绑定，需新设备重新生成
+- `.claude/.pending-init` —— 由 session-init Hook 创建的标记文件（若存在）
+
+**B. 重置为空模板**（保留文件，仅清内容）
+
+| 文件 | 模板（见"模板内容"节） |
+|------|------------------------|
+| `.claude/changelog/changelog-full.md` | L1 模板 |
+| `.claude/changelog/changelog-recent.md` | L2 模板 |
+| `.claude/changelog/changelog-headlines.md` | L3 模板 |
+| `.claude/changelog/.changelog-ack` | 空文件（touch） |
+| `.claude/deferred/registry.md` | deferred 模板 |
+| `.claude/pitfalls/pitfalls.md` | pitfalls 模板 |
+| `.claude/distillery/problems.md` | problems 模板 |
+| `.claude/distillery/insights.md` | insights 模板 |
+| `.claude/distillery/golden-rules.md` | golden-rules 模板 |
+| `.claude/profile/project-profile.md` | project-profile 模板 |
+| `.claude/profile/project-profile-log.md` | project-profile-log 模板 |
+
+执行要点：
+
+- 每个重置前**先 Read 现有内容预览前 10 行**给用户，避免误删有价值数据（特别是 deferred/pitfalls 用户可能想保留）
+- 如用户对某个数据文件明确说"保留"（例如 golden-rules 想带过去），跳过该文件的重置
+
+### 阶段 4：重建 registry
+
+打开 `.claude/skills/epee-orchestrator/registry.md`：
+
+1. 解析现有条目（每条 `### <skill-name>` 块）
+2. 删除所有 `类型: 项目级` 的条目
+3. 遍历 `.claude/skills/` 目录，对照 registry：
+   - registry 有条目但 skill 目录不存在 → 删除条目
+   - skill 目录存在但 registry 无条目 → 读取该 skill 的 SKILL.md frontmatter，新增条目
+4. **确保 `claude-init` 条目本身存在**（类型: 基础设施）
+5. 写回 registry.md
+
+### 阶段 5：同步 `settings.json`（跨平台保守处理）
+
+- 读取 `.claude/settings.json`
+- 若 `hooks` 字段中 `command` 硬编码为 `powershell ...`，且目标新项目声明/探测到的 shell 不是 powershell，**提醒用户**需要按 `hooks/README.md` 手动改为 `bash .claude/hooks/xxx.sh`
+- 本阶段不自动改 settings.json，避免误判
+
+### 阶段 5.5：`.gitignore` 交互式生成
+
+#### 5.5.1 前置检测
+
+```
+检测项目根 .gitignore：
+  不存在        → 进入 5.5.2 问卷
+  已存在且非空  → Read 前 30 行展示给用户，询问：
+                  [覆盖 / 追加到文件末尾 / 跳过本阶段]
+  用户选"跳过"  → 本阶段结束，.init-done 里标记 gitignore_generated: false
+```
+
+#### 5.5.2 问卷（一次性批量 AskUserQuestion 收集）
+
+必问 3 项 + 可选 1 项：
+
+| 编号 | 问题 | 类型 | 选项 |
+|------|------|------|------|
+| Q1 | 项目主要技术栈 | 多选 | Unity / Node.js / Python / Rust / Go / C# 非 Unity / Web 静态站点 / 其他 / **不确定（跳过语言段）** |
+| Q2 | IDE 偏好 | 多选 | Cursor / VSCode / JetBrains 全家桶 / Visual Studio / Vim+Emacs |
+| Q3 | 操作系统 | 多选 | Windows / macOS / Linux（按探测到的当前 OS 预勾） |
+| Q4（可选）| 其他要忽略的路径 | 自由文本 | 用户可跳过 |
+
+#### 5.5.3 片段组装
+
+按问卷选择拼装，片段内容见下方"模板内容 · .gitignore 片段库"。拼装顺序固定：
+
+```
+# === Claude（固定，所有项目都包含） ===
+# === OS ===
+# === IDE ===
+# === Language / Framework ===
+# === Custom ===
+```
+
+若 Q1 选"不确定" → 跳过 Language 段，其他段正常拼装（极简版仍可用）。
+
+#### 5.5.4 预览与确认
+
+1. 把组装结果写到 `.claude/_gitignore-preview`（临时文件）
+2. 给用户完整展示（超过 60 行则折叠中段）
+3. AskUserQuestion：`[写入 .gitignore / 让我调整再确认 / 放弃本阶段]`
+4. "写入"→ move 到项目根 `.gitignore`（已存在时按 5.5.1 的选择做覆盖或追加），删除预览文件
+5. "调整"→ 根据用户描述修改后重复步骤 2-3
+6. "放弃"→ 删除预览文件，`.init-done` 标记 `gitignore_generated: false`
+
+### 阶段 6：验证与报告
+
+```
+1. 重新递归扫描 .claude/，再次分组
+2. 期望状态：
+   - A 组：全部保留，文件内容未被动过
+   - B 组：数据文件仅含模板内容；项目级 rules/skills/日志 已删除
+   - C 组：为空（或仅剩用户明确要求保留的文件）
+   - 项目根 .gitignore：按用户选择存在或被放弃（状态记到报告里）
+   - CLAUDE.md：@import 引用与实际 rules 目录内容一致
+3. 给用户一份结构化报告，至少包含：
+   - 移动的文件（from → to）
+   - 删除的文件
+   - 重置的文件
+   - CLAUDE.md 中新增/删除的 @import 行
+   - .gitignore 的处理结果（新建/追加/覆盖/放弃）
+   - 未处理的文件（如果有，逐条说明原因）
+```
+
+### 阶段 7：写入 `.init-done` sentinel
+
+**仅在阶段 6 验证全部通过后执行**。任何前序阶段异常中断都不写入此文件，确保下次会话 recall 能再次触发。
+
+```
+1. 按"模板内容 · .init-done"格式，填充实际值写入 .claude/.init-done
+2. 删除 .claude/.pending-init（由 session-init Hook 创建，sentinel 存在后不再需要）
+3. 向用户输出收尾提示：
+   > 初始化完成。建议现在执行：
+   >   git add .claude/ .gitignore
+   >   git diff --cached -- .claude/
+   >   git commit -m "chore(claude): initialize .claude from template"
+   >
+   > ⚠️ .claude/.init-done 必须 commit，否则团队其他成员 clone 后会被再次触发 init。
+```
+
+**仅跑阶段 5.5 时**（用户说"补 gitignore"）：
+- 若 `.init-done` 存在 → 更新其中的 `gitignore_generated: true` 字段，保留其他字段
+- 若 `.init-done` 不存在 → 提示用户"仓库尚未完整 init，只补 gitignore 不会写 sentinel。是否改为跑完整 init？"
+
+---
+
+## 规范清单（canonical）
+
+下列文件构成本 `.claude` 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外）：
+
+### 顶层
+
+- `.claude/CLAUDE.md`
+- `.claude/settings.json`
+- `.claude/settings.local.example.json`
+- `.claude/.init-done` —— **阶段 7 写入**；模板仓库自身不应包含此文件
+
+### Rules（通用）
+
+- `.claude/rules/common/baserule.md`
+- `.claude/rules/common/claude-init-recall.md`
+- `.claude/rules/common/changelog-recall.md`
+- `.claude/rules/common/deferred-recall.md`
+- `.claude/rules/common/distillery-recall.md`
+- `.claude/rules/common/epee-orchestrator.md`
+- `.claude/rules/common/pitfall-recall.md`
+- `.claude/rules/common/profile-recall.md`
+
+### Rules（项目专属目录）
+
+- `.claude/rules/project/`（保留**空目录**；源项目的 `.md` 内容一律删除）
+
+### Skills（规范 Skill 目录白名单）
+
+- `.claude/skills/claude-init/`
+- `.claude/skills/deferred-decisions/`
+- `.claude/skills/dev-changelog/`
+- `.claude/skills/epee-orchestrator/`（含 `registry.md`，见阶段 4）
+- `.claude/skills/pitfall-journal/`
+- `.claude/skills/problem-distillery/`
+- `.claude/skills/profile-memory/`
+
+> **任何不在此白名单中的 skill 目录**，在阶段 3 中一律删除（视为源项目的项目级 Skill）。
+
+### Hooks
+
+- `.claude/hooks/README.md`
+- `.claude/hooks/run-hook.ps1`
+- `.claude/hooks/session-init.ps1`
+- `.claude/hooks/session-init.sh`
+- `.claude/hooks/check-changelog.ps1`
+- `.claude/hooks/check-changelog.sh`
+
+### 数据占位目录（保留目录，文件重置为模板内容）
+
+- `.claude/changelog/{changelog-full.md, changelog-recent.md, changelog-headlines.md, .changelog-ack}`
+- `.claude/deferred/registry.md`
+- `.claude/pitfalls/pitfalls.md`
+- `.claude/distillery/{problems.md, insights.md, golden-rules.md}`
+- `.claude/profile/{project-profile.md, project-profile-log.md}`
+- `.claude/plans/`（空目录）
+
+---
+
+## 清理清单（cleanup list）
+
+### 强制删除
+
+| 路径 | 原因 |
+|------|------|
+| `.claude/rules/project/*.md` | 源项目的项目级 Rules |
+| `.claude/skills/<非白名单>/` | 源项目的项目级 Skills |
+| `.claude/plans/*`（内容） | 源项目规划文档（若目录存在） |
+| `.claude/*.log`、`.claude/debug-*.log` | 调试日志遗留 |
+| `.claude/settings.local.json` | 设备绑定配置，需由新设备重新生成 |
+| `.claude/local-env.json` | 设备绑定配置，需由新设备重新生成 |
+| `.claude/_init-backup/`（如果是上一轮残留） | 仅阶段 2 冲突备份用，运行前应不存在 |
+| `.claude/_gitignore-preview`（如果是上一轮残留） | 阶段 5.5 临时文件 |
+
+### CLAUDE.md 同步清理
+
+阶段 3A 删除 `rules/project/*.md` 后，必须打开项目根 `CLAUDE.md`，移除其中引用的
+`@rules/project/...` 行。保留"项目专属规则"段标题和注释占位，方便用户后续新增。
+
+### 重置为模板
+
+见"模板内容"节。
+
+---
+
+## 模板内容
+
+重置数据文件时使用以下内容。带 `{{DATE}}` 的占位符替换为当天日期（`YYYY-MM-DD`）。
+
+### changelog-full.md
+
+```markdown
+# Dev Changelog — Full
+
+完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
+
+## 记录
+```
+
+### changelog-recent.md
+
+```markdown
+# Dev Changelog — Recent
+
+最近 ~10 次改动的摘要记录，按时间倒序排列。
+当 Agent 检测到当前任务与近期改动相关时自动读取。
+```
+
+### changelog-headlines.md
+
+```markdown
+# Dev Changelog — Headlines
+
+最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
+```
+
+### .changelog-ack
+
+空文件（0 字节），只用于更新 mtime 阻止 hook 重复提醒。
+
+### deferred/registry.md
+
+```markdown
+# Deferred Decisions Registry
+
+## Active Items
+
+（暂无延期方案）
+
+---
+
+## Completed / Cancelled Items
+
+（暂无已完成或已废弃的方案）
+```
+
+### pitfalls/pitfalls.md
+
+```markdown
+# Pitfall Journal
+
+开发过程中踩过的坑，按时间倒序排列。
+Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。
+
+---
+```
+
+### distillery/problems.md
+
+```markdown
+# Problem Distillery — Problems
+
+反复出现的顽固问题追踪记录，按时间倒序排列。
+
+<!-- 新条目追加在此行下方 -->
+```
+
+### distillery/insights.md
+
+```markdown
+# Problem Distillery — Insights
+
+从已解决的顽固问题中蒸馏出的精炼方法论。
+
+<!-- 新条目追加在此行下方 -->
+
+---
+last_distill_date: {{DATE}}
+```
+
+### distillery/golden-rules.md
+
+```markdown
+# Golden Rules
+
+经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
+
+<!-- 当条目达到权重阈值后由 Agent 自动写入 -->
+```
+
+### profile/project-profile.md
+
+```markdown
+# Project Profile
+
+## 项目定位
+
+## 技术栈与架构
+
+## 设计约定
+
+## 产品方向
+```
+
+### profile/project-profile-log.md
+
+```markdown
+# Project Profile Log
+
+详细记录每次项目画像更新的完整上下文，按时间正序追加。
+
+## 记录
+```
+
+### .init-done
+
+阶段 7 写入的 sentinel，YAML 格式，字段固定：
+
+```yaml
+# .claude/.init-done — claude-init Skill 写入的初始化标记文件
+# 本文件的存在表示本仓库已完成 .claude 模板初始化
+# 请务必 git commit 此文件，避免团队成员 clone 后被再次触发 init
+initialized_at: {{ISO_DATETIME}}      # 如 2026-04-23T16:30:00+08:00
+initialized_by: claude-init
+skill_version: 2
+project_type: {{PROJECT_TYPE}}        # 阶段 5.5 问卷 Q1 结果；多选逗号分隔；"不确定"写 unknown
+gitignore_generated: {{BOOL}}         # true / false
+```
+
+**写入时机**：
+- 全流程跑完（阶段 6 验证通过）时由阶段 7 写入
+- "补 gitignore" 单独跑阶段 5.5 时，若已存在则只更新 `gitignore_generated` 字段
+
+---
+
+## 模板内容 · .gitignore 片段库
+
+阶段 5.5 按用户问卷选择拼接以下片段。每段前后各空一行，保证可读性。
+
+### 固定段：Claude
+
+```gitignore
+# === Claude ===
+# 设备绑定配置，不同机器需独立生成
+.claude/settings.local.json
+
+# Hook 运行态标记（仅影响本地会话）
+.claude/changelog/.changelog-ack
+
+# claude-init 临时产物
+.claude/_init-backup/
+.claude/_gitignore-preview
+```
+
+### OS 段（按问卷 Q3 多选拼接）
+
+**Windows**
+
+```gitignore
+# === OS: Windows ===
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+Desktop.ini
+$RECYCLE.BIN/
+*.stackdump
+*.lnk
+```
+
+**macOS**
+
+```gitignore
+# === OS: macOS ===
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+```
+
+**Linux**
+
+```gitignore
+# === OS: Linux ===
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+```
+
+### IDE 段（按问卷 Q2 多选拼接）
+
+**Cursor**
+
+```gitignore
+# === IDE: Cursor ===
+.cursor/local-env.json
+.cursor/_init-backup/
+.cursor/_gitignore-preview
+```
+
+**VSCode**
+
+```gitignore
+# === IDE: VSCode ===
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.history/
+*.vsix
+```
+
+**JetBrains**
+
+```gitignore
+# === IDE: JetBrains ===
+.idea/
+*.iml
+*.ipr
+*.iws
+.idea_modules/
+atlassian-ide-plugin.xml
+```
+
+**Visual Studio**
+
+```gitignore
+# === IDE: Visual Studio ===
+.vs/
+*.user
+*.suo
+*.userprefs
+bin/
+obj/
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+```
+
+**Vim/Emacs**
+
+```gitignore
+# === IDE: Vim / Emacs ===
+*.swp
+*.swo
+*.swn
+Session.vim
+.netrwhist
+*~
+\#*\#
+.\#*
+```
+
+### Language / Framework 段（按问卷 Q1 多选拼接）
+
+**Unity**
+
+```gitignore
+# === Language: Unity ===
+[Ll]ibrary/
+[Tt]emp/
+[Oo]bj/
+[Bb]uild/
+[Bb]uilds/
+[Ll]ogs/
+[Uu]ser[Ss]ettings/
+[Mm]emoryCaptures/
+[Rr]ecordings/
+sysinfo.txt
+*.apk
+*.aab
+*.unitypackage
+*.app
+*.csproj
+*.unityproj
+*.sln
+*.suo
+*.tmp
+*.user
+*.userprefs
+*.pidb
+*.booproj
+*.svd
+*.pdb
+*.mdb
+*.opendb
+*.VC.db
+```
+
+**Node.js**
+
+```gitignore
+# === Language: Node.js ===
+node_modules/
+.npm/
+.yarn/
+.pnp.*
+dist/
+build/
+out/
+.next/
+.nuxt/
+.cache/
+.parcel-cache/
+coverage/
+.env
+.env.local
+.env.*.local
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.turbo/
+```
+
+**Python**
+
+```gitignore
+# === Language: Python ===
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+.ipynb_checkpoints/
+```
+
+**Rust**
+
+```gitignore
+# === Language: Rust ===
+target/
+**/*.rs.bk
+*.pdb
+# Cargo.lock：lib crate 建议忽略，bin crate 建议提交，默认不忽略
+# Cargo.lock
+```
+
+**Go**
+
+```gitignore
+# === Language: Go ===
+bin/
+vendor/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work
+```
+
+**C# 非 Unity**
+
+```gitignore
+# === Language: C# (non-Unity) ===
+bin/
+obj/
+*.user
+*.suo
+*.pdb
+*.cache
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+[Bb]uild/
+*.dll
+*.pdb
+```
+
+**Web 静态站点**
+
+```gitignore
+# === Language: Web Static ===
+node_modules/
+dist/
+build/
+public/build/
+.cache/
+.tmp/
+.sass-cache/
+.parcel-cache/
+```
+
+**其他**：不拼接语言段，用户在 `# === Custom ===` 段自行补充。
+
+### Custom 段（固定尾部）
+
+```gitignore
+# === Custom ===
+# 在此段追加项目专属需要忽略的路径
+```
+
+若用户在问卷 Q4 填了自由文本，按行拆分后追加到 Custom 段下方。
+
+---
+
+## 冲突与边界情况处理
+
+| 场景 | 处理 |
+|------|------|
+| C 组某文件与 A 组重名 | 保留 A 组；C 组移到 `.claude/_init-backup/`，告知用户自行 diff |
+| C 组有 `SKILL.md` 且 skill 名与 A 组白名单同名 | 保留 A 组 skill；C 组整个 skill 目录移到 `_init-backup/` |
+| 数据文件用户明确说"保留" | 跳过该文件重置 |
+| `settings.local.json` 存在且用户说"我就在这台机器上开 B，保留它" | 跳过删除，但执行以下校验：1) 扫描文件中所有绝对路径（如 `D:/GIT_HOME/xxx`、`/home/user/xxx`），与当前工作目录比对；2) 路径不一致的逐条列出并提醒用户修正；3) 提醒该文件已在 `.gitignore` 中 |
+| `.claude/rules/project/` 为空目录 | 保留空目录（便于未来放项目级 rules） |
+| 扫描到 `.claude/_init-backup/`（上轮残留） | 警告用户并询问：删除 / 保留 / 重命名 |
+| `git status` 不能执行（不是 git 仓库） | 警告但不阻塞，改为建议用户手动备份 |
+| `.claude/.init-done` 已存在且用户触发了全流程 | 阶段 0 展示其元数据并要求二次确认 |
+| 阶段 5.5 项目根已有 `.gitignore` 且用户选"追加" | 把拼装结果追加到现有文件末尾（用 `\n\n# --- 以下由 claude-init 追加 ---\n` 分隔） |
+| 阶段 5.5 中途异常或用户放弃 | 不写入 `.gitignore`，`.init-done` 的 `gitignore_generated` 记 false |
+| 阶段 7 写 `.init-done` 前前序阶段已 abort | 不写入 sentinel，下次会话 recall 会重新触发 |
+| 用户说"补 gitignore" 但 `.init-done` 不存在 | 提醒"仓库尚未完整 init"，询问是否改为跑全流程 |
+
+---
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `baserule.md` | 分类权威 | 阶段 2 归位目录严格按 baserule 约定 |
+| `claude-init-recall.md` | 触发器 | 负责首次自动触发（alwaysApply + sentinel 检查）和关键词触发 |
+| `CLAUDE.md` | 双向依赖 | 阶段 2/3 要同步更新主文件的 `@import` 引用行 |
+| `epee-orchestrator` Skill | 双向 | 本 Skill 被 Orchestrator 在 registry 里注册；同时本 Skill 负责清理 registry |
+| `dev-changelog` / `pitfall-journal` / `deferred-decisions` / `problem-distillery` / `profile-memory` | 下游数据主人 | 本 Skill 只在阶段 3 重置其数据文件，不改动 SKILL.md |
+| `settings.local.json` | 后继 | 本 Skill 删除此文件，后续由用户参照 example 手工生成 |
+
+---
+
+## 一次运行的最终状态（验收标准）
+
+全流程（阶段 0 → 7）完成后 `.claude/` 应当满足：
+
+1. 规范清单中列出的所有文件/目录都存在
+2. 所有数据文件（changelog/deferred/pitfalls/distillery/profile）仅含模板内容
+3. `.claude/rules/project/` 为空目录
+4. `.claude/skills/` 下仅有白名单中的 skill 目录
+5. `.claude/skills/epee-orchestrator/registry.md` 中只有：基础设施 + 个人级 skill 条目，且包含 `claude-init` 条目
+6. 不存在 `*.log`、`settings.local.json`、`local-env.json`、`_init-backup/`、`_gitignore-preview`
+7. `CLAUDE.md` 中的 `@import` 引用与实际 rules 目录内容一致（不含已删除的 project rules）
+8. `.claude/.init-done` 已写入，字段完整且值有效
+9. 项目根 `.gitignore` 状态明确（存在且有内容 / 被用户显式放弃）
+10. `git status .claude/ .gitignore` 能让用户清楚看到所有改动
+
+仅跑阶段 5.5（"补 gitignore"）完成后：
+
+1. 项目根 `.gitignore` 存在或被显式放弃
+2. 若 `.init-done` 已存在，其 `gitignore_generated` 字段被更新
+3. 其他 `.claude/` 内容**零改动**
+
+---
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+1. **阶段 2 的 C 组归位前必须先做 dry-run 展示** —— 批量移动 .md / SKILL 文件是高破坏性操作，只要有一条分类错误就会污染 canonical 结构，必须让用户在列表上逐条过一遍再执行。
+
+2. **重名冲突不许直接覆盖** —— C 组与 A 组重名时，A 组（模板版本）永远是 source of truth，冲突文件只能进 `_init-backup/`，让用户自行决定是否把差异合并回 common rule。
+
+3. **`.init-done` 是完成度契约** —— 只有阶段 6 验证通过后才能写入此文件。中途 abort 必须让 sentinel 缺失，这是保证下次会话能恢复触发的关键设计。
+
+4. **`.gitignore` 用户主导** —— 阶段 5.5 对语言栈/IDE/OS 的判断完全来自用户问卷，不要根据文件探测"智能推断"，因为新项目此时通常还是空白，推断不准反而会填错条目。
+
+5. **`CLAUDE.md` 是 Rule 触发的入口** —— 与 Cursor 不同，Claude Code 的 rules 不会因为 `alwaysApply: true` frontmatter 而自动注入——必须通过 `CLAUDE.md` 的 `@import` 引入。任何对 `rules/common/` 或 `rules/project/` 目录的增删都必须同步更新 `CLAUDE.md`。
+
+6. **保留 `settings.local.json` 时必须校验路径** —— 用户选择保留该文件时，必须扫描其中所有绝对路径（通常出现在 `permissions.allow` 的 Bash 命令中），与当前项目根目录比对。路径不一致的逐条列出提醒用户修正。此检查防止从模板 clone 后路径指向错误项目。