claude init inited

.claude/rules/common/baserule.md

@@ -0,0 +1,49 @@
+## 语言约定
+
+Agent 回复时使用简体中文。
+代码注释时尽量使用简体中文。
+写 SKILL 的时候文档部分也尽量使用简体中文。
+专业术语和项目专有名词不受此语言限制，通常是英文则保留（如 `frontmatter`、`hook`、`token`、`MCP`、`Claude Code`、`GitHub` 等）。
+
+## Rules / Skills 目录归属约定
+
+本项目使用以下目录结构区分跨项目通用内容与项目专属内容：
+
+### Rules
+
+| 目录 | 用途 | 示例 |
+|------|------|------|
+| `.claude/rules/common/` | 跨项目通用规则，开新项目时可直接复制 | 语言约定、init 触发、changelog 调用 |
+| `.claude/rules/project/` | 当前项目专属规则 | 项目架构约定、框架特定规范、项目专属工作流 |
+
+Rules 的引入通过主 `CLAUDE.md` 的 `@import` 语法进行，每条规则独立一个文件。
+
+### Skills
+
+| 位置 | 用途 | 示例 |
+|------|------|------|
+| `.claude/skills/` | **所有 Skill 的主存储位置**（含通用和项目专属） | claude-init、dev-changelog、项目特定 Skill |
+| `~/.claude/skills/` | 跨项目通用 Skill 的全局副本（可选，方便其他项目复用） | claude-init、dev-changelog |
+
+> **重要**：无论 Skill 是通用还是项目专属，都**必须**在项目的 `.claude/skills/` 下保留一份，
+> 以确保能被 Git 管理和版本控制。全局目录 `~/.claude/skills/` 仅作为跨项目共享的便利副本，
+> 不作为唯一存储位置。
+
+### Agent 创建 Rule 或 Skill 时必须遵守
+
+1. **先判断归属**：新建 Rule 或 Skill 前，评估其是否为跨项目通用内容
+2. **如果不确定，必须询问用户**："这个 Rule/Skill 是通用的还是项目专属的？"
+3. 确认后放入对应目录：
+   - 通用 Rule → `.claude/rules/common/<name>.md` + 在 `CLAUDE.md` 的"引入的规则"段追加 `@import`
+   - 项目专属 Rule → `.claude/rules/project/<name>.md` + 在 `CLAUDE.md` 的"项目专属规则"段追加 `@import`
+   - **所有 Skill（含通用）→ `.claude/skills/<skill-name>/SKILL.md`**（必须，确保 Git 可管理）
+   - 通用 Skill 额外同步 → `~/.claude/skills/<skill-name>/SKILL.md`（可选，方便其他项目使用）
+
+### Skill 的 frontmatter 规范
+
+新建 Skill 时 `SKILL.md` 的 YAML frontmatter 必须符合 Claude Code 官方规范：
+
+- `name`: 最多 64 字符，仅小写字母/数字/连字符，不含保留词 `anthropic` 或 `claude`
+- `description`: 最多 1024 字符，非空，**第三人称**，包含"做什么 + 何时使用"的触发关键词
+
+详见 Anthropic 官方文档：<https://code.claude.com/docs/en/skills>

.claude/rules/common/changelog-recall.md

@@ -0,0 +1,120 @@
+## 开发日志上下文注入
+
+每次会话处理用户第一个任务前，执行以下操作：
+
+1. 读取 `.claude/changelog/changelog-headlines.md`（不存在则跳过）
+2. 如文件存在且有实质内容（不仅是模板头部），将全部条目作为背景知识注入上下文
+3. 这些信息帮助 Agent 快速建立位置感：项目进展到什么阶段、最近的工作重心在哪个模块
+4. 在后续回复中自然参考，不显式提及"根据开发日志"
+
+## 主动定位辅助
+
+L3 概要的核心价值之一是帮助 Agent 在**冷启动**（新会话、无上下文）时理解用户意图。
+当用户的请求缺少具体文件名或模块名时，Agent 应主动利用 L3 进行推断：
+
+### 典型场景
+
+1. **隐式延续**：用户说"继续做昨天那个"、"把那个功能完善一下"
+   → 从 L3 中找到最近的相关条目，上溯到 L2 获取具体文件列表
+2. **模糊指代**：用户说"那个组件有 bug"、"之前改的那个接口"
+   → 用 L3 中的关键词匹配用户描述，定位到具体改动
+3. **上下文补全**：用户直接提出一个任务，没有背景说明
+   → 用 L3 判断该任务是否与近期某个改动有关联（如同一模块、同一功能线）
+
+### 流程
+
+```
+1. 解析用户请求，识别是否存在隐式引用或模糊指代
+2. 在 L3 概要中查找语义最匹配的 1-3 条记录
+3. 提取匹配条目的锚点 ID，上溯到 L2 获取 affected_files 和 tags
+4. 如有必要，继续上溯到 L1 获取完整的决策背景
+5. 将定位到的文件/模块作为任务的起点，开始执行
+```
+
+如果 L3 中没有匹配到任何相关记录，正常处理即可——不是所有任务都与近期改动有关。
+
+## L2 自动触发
+
+Agent 开始处理一个新任务时，判断是否需要读取近期详细记录：
+
+1. 从当前任务中提取涉及的文件路径和语义关键词
+2. 与 L3 概要中的内容做快速比对——如果近期有相关模块/文件的改动记录
+3. 命中时，读取 `.claude/changelog/changelog-recent.md`，将相关条目纳入上下文
+4. 匹配策略：
+   - 硬匹配：当前任务涉及的文件出现在 L2 条目的 `affected_files` 中
+   - 软匹配：当前任务的语义关键词与条目的 `tags` 有交集
+   - 任一命中即触发读取
+
+### 注意
+
+- L3 注入是低成本操作（~50 句话），每次会话都执行
+- L2 读取按需触发，只在检测到关联时才读取
+- 开发日志是事实性记录，直接使用即可，不像画像那样需要"自然融入"的措辞考量
+- 记录的写入和管理由 `dev-changelog` Skill 负责，本 Rule 只负责读取和注入
+
+## 逐级上溯
+
+当 L3 中某条记录的一句话描述**语义模糊**（无法判断具体范围或与当前任务的关系），
+按以下步骤精准上溯，**禁止全文读取 L1**：
+
+1. 提取该条目的锚点 ID（`CL-xxx`）
+2. 用 Grep 在 `changelog-recent.md`（L2）中搜索该 ID → 找到则读取该条目
+3. 如 L2 中未找到或仍有歧义 → 用 Grep 在 `changelog-full.md`（L1）中搜索该 ID，
+   获取行号后用 Read 工具读取该行号 ±20 行范围
+4. 一次上溯通常只涉及 1-3 条记录，不批量上溯
+
+## 任务完成 Checklist（强制）
+
+Agent 在即将输出最终回复前，**必须**逐项检查以下清单。
+这是硬性要求，不是建议——**跳过任何一项都视为执行错误**。
+
+### 前置项（每次回复前无条件执行）
+
+**A. 画像信号扫描（短路版）**
+
+目的：以最小 token 成本维持 `profile-memory` Skill 的被动检测通路。
+
+步骤：
+
+1. **快判（词表匹配）**：扫描本次对话中**用户消息**，检查是否**明显**出现以下偏好/决策触发词族之一：
+
+   - 个人偏好信号：`我喜欢` / `我倾向` / `我不喜欢` / `我讨厌` / `以后都` / `以后别` /
+     `别再` / `不要再` / `我的风格` / `我的偏好` / `太花哨` / `minimal` /
+     `简洁` / `精炼` / `啰嗦`
+   - 项目决策信号：`这个项目是` / `目标用户是` / `技术栈` / `架构上` /
+     `产品方向` / `定位是`
+
+2. **分支**：
+   - 无匹配 → **直接跳过**，进入下一 checklist 项（thinking 应在 50 token 内结束）
+   - 有匹配 → 读取 `.claude/skills/profile-memory/SKILL.md` 并执行操作 A 的确认流程
+
+3. **约束**：本项不做全量语义判断——漏记隐式信号是可接受的权衡。
+   用户如需记录隐式偏好可显式说"把这条记入画像"。
+
+### 变更检查项（仅当本次有代码/配置文件改动时执行）
+
+1. **本次是否有代码/配置文件改动？**（不含 `.claude/` 下的基础设施文件）
+   - 否 → 跳过本组后续项，直接进入"收尾项"
+   - 是 → 继续
+
+2. **是否已写入三层开发日志？**
+   - 否 → **立即**读取 `dev-changelog` Skill 并执行操作 A，写入 L1 + L2 + L3 后再输出回复
+   - 是 → 继续
+
+3. **是否修改了任何 Skill？**（包括 SKILL.md 内容变更）
+   - 否 → 跳过
+   - 是 → 检查是否已同步 `epee-orchestrator` 的 `registry.md`，未同步则立即执行
+
+4. **本次是否有 Skill 使用异常？**（遗漏、误触、产物与用户预期偏差）
+   - 否 → 跳过
+   - 是 → 执行 `epee-orchestrator.md` 中的自迭代确认流程
+
+### 收尾项（每次回复前无条件执行）
+
+**Z. 静默 Hook ack**
+
+- 用 Write 工具创建空文件 `.claude/changelog/.changelog-ack`
+- 这会更新 ack 文件的 mtime，阻止 `check-changelog` hook 在后续回复中重复提醒
+
+**执行原则**：先完成 checklist 中的所有写入动作，再输出面向用户的回复文本。
+回复末尾如果执行了变更检查项第 2 项，附 `[已记录到开发日志]`。

.claude/rules/common/claude-init-recall.md

@@ -0,0 +1,90 @@
+## 首次初始化自检（最高优先级 · 必须最先执行）
+
+**每一次会话的首次用户消息响应之前**，Agent 必须执行以下检测（二选一，按优先级）：
+
+### 检测方式
+
+**方式 1（优先）：检查 `.claude/.pending-init` 标记文件。**
+
+此文件由 `session-init` Hook **确定性创建**（不依赖 Agent 记忆）：
+- Hook 在 SessionStart 时运行
+- `.init-done` 不存在 → Hook 创建 `.pending-init`
+- `.init-done` 存在 → Hook 删除 `.pending-init`（清理残留）
+
+Agent 只需 `Read .claude/.pending-init`：
+- 文件存在 → 首次会话，必须触发 claude-init
+- 文件不存在 → 已初始化，跳过
+
+**方式 2（兜底）：直接检查 `.claude/.init-done`。**
+
+若方式 1 未执行（Hook 未配置或未运行），回退到直接检查 sentinel。
+
+### 判定逻辑
+
+```
+IF .claude/.pending-init 存在 OR .claude/.init-done 不存在:
+    → 本仓库是"clone 模板后的首次会话"
+    → 必须在处理用户原始请求之前先完成 claude-init
+ELSE:
+    → 已 init 过，跳过本自检
+    → 仅当用户命中下方"手动触发关键词"时才再次执行本 Skill
+```
+
+### 首次触发的执行方式
+
+1. **暂存用户原始请求**，明确告诉用户：
+   > "检测到当前仓库刚从模板 clone 下来，还未完成 .claude 初始化。需要先跑一遍 claude-init
+   > （清理模板遗留数据、配置项目画像、可选生成 .gitignore）。完成后再处理你的请求：{原始请求概要}。"
+2. 等用户明确回复"继续/OK"后，读取 `.claude/skills/claude-init/SKILL.md` 并严格执行阶段 0 → 7
+3. **init 完成后**（阶段 7 写入 `.init-done` 成功后），回到被暂存的用户原始请求继续处理
+4. 若用户说"先不做 init，就处理我的请求"：
+   - 尊重用户选择，跳过本次 init
+   - 但仍在本次回复中明确说明 sentinel 缺失，并提示"下次会话还会再次提醒"
+
+### 自检成本说明
+
+已 init 项目：每次会话仅多一次 `Read .claude/.pending-init`（极低成本，文件不存在时 Read 返回 error 即视为"已初始化"）。
+`.pending-init` 由 Hook 维护，Agent 无需写入。
+
+---
+
+## 手动触发关键词（任意时刻，已 init 仓库也可用）
+
+### A. 全流程重置（阶段 0 → 7）
+
+匹配任一：
+- "初始化 claude" / "初始化claude" / "claude 初始化"
+- "重置 claude" / "reset claude"
+- "claude init" / "init claude"
+- "把复制过来的 .claude 清理一下" / "按 baserule 归位一下"
+
+**执行方式**：读取 `.claude/skills/claude-init/SKILL.md`，按阶段 0 → 7 执行。
+若 `.claude/.init-done` 已存在，阶段 0 会展示其元数据并要求用户二次确认。
+
+### B. 仅补 .gitignore（只跑阶段 5.5）
+
+匹配任一：
+- "补 gitignore" / "补一下 gitignore" / "补个 gitignore"
+- "生成 gitignore" / "生成 .gitignore"
+- "gitignore 模板" / "来份 gitignore"
+
+**执行方式**：读取 SKILL.md 的**阶段 5.5 章节**单独执行，不触碰其他阶段。
+完成后更新 `.init-done` 中的 `gitignore_generated: true`。
+
+---
+
+## 执行原则
+
+1. **稳定准确优先于 token 成本**
+2. 破坏性操作（删除、重置、移动）前必须给用户 dry-run 清单
+3. 分类不清的文件必须逐条询问用户，不要猜
+4. 开始前先执行 `git status` 并提醒用户 commit/stash
+5. 设计为幂等——重复运行在已干净状态下不应造成破坏
+
+---
+
+## 不触发本 Skill 的情况
+
+- 用户只是问"claude 有什么 skill" —— 这是浏览需求，后续阶段会由 `epee-orchestrator` 类 Skill 处理
+- 用户只是想初始化某个具体数据文件（如"初始化画像"）—— 走对应 Skill，不涉及全局重置
+- `.claude/.init-done` 存在 且 用户请求中**没有**任一 A/B 组关键词 —— 正常响应用户，不提 init

.claude/rules/common/deferred-recall.md

@@ -0,0 +1,16 @@
+## 延期方案主动回忆
+
+每次会话处理用户第一个任务前，执行以下检查：
+
+1. 读取 `.claude/deferred/registry.md`（不存在则跳过）
+2. 扫描所有 `status: deferred` 的条目
+3. 将每个条目的 **tags** 和 **related_files** 与当前任务的关键词/文件做匹配
+4. 如果匹配到关联条目，在回复开头简要提醒：
+   > 提醒：你之前有一个延期方案 **[标题]** 与当前任务相关（tags: xxx）。要一并处理吗？
+5. 每个条目每次会话最多提醒一次，不重复打扰
+
+### 注意
+
+- 只匹配 `status: deferred` 的条目（`reminded` / `in_progress` 不再提醒）
+- 提醒应简洁，不超过 2 行，不打断用户主线任务
+- 具体的记录/管理操作请参考 `deferred-decisions` Skill

.claude/rules/common/distillery-recall.md

@@ -0,0 +1,44 @@
+## Problem Distillery 上下文注入
+
+### Golden Rules 注入
+
+每次会话处理用户第一个任务前，执行以下操作：
+
+1. 读取 `.claude/distillery/golden-rules.md`（不存在则跳过）
+2. 如文件存在且有实质条目（不仅是标题），将全部条目作为背景知识注入上下文
+3. 这些是经过实践反复验证的精炼认知，Agent 在分析和解决问题时应自然参考
+4. 不需要在回复中显式提及"根据 Golden Rule"
+
+### 蒸馏提醒检查
+
+每次会话处理用户第一个任务前，额外检查：
+
+1. 读取 `.claude/distillery/insights.md`（不存在则跳过）
+2. 检查文件尾部的 `last_distill_date` 字段
+3. 如果距今超过 7 天，读取 `.claude/distillery/problems.md`
+4. 统计 `status: resolved` 且无 `distilled:` 标记的条目数量
+5. 如有未蒸馏的已解决条目，提醒用户：
+   > 你有 N 个已解决的顽固问题尚未总结，要花几分钟蒸馏一下吗？
+6. 每次会话最多提醒一次
+
+### 顽固问题检测
+
+Agent 在整个对话过程中应保持对以下信号的被动感知：
+
+1. 用户表达问题未解决："还有问题"、"没解决"、"还是一样"、"又出现了"、"不行"、"没用"
+2. Agent 自身意识到同一问题已尝试 2 次以上仍未解决
+3. pitfall-journal 中已有记录的问题再次出现
+
+检测到上述信号时，读取 `problem-distillery` Skill 并执行其操作 A。
+
+### 验证触发
+
+当操作 A 触发时（追踪新的或再次出现的顽固问题），如果 `insights.md` 非空，
+还应执行操作 D 的被动验证流程——匹配是否有相关的已蒸馏经验可供参考。
+
+### 注意
+
+- Golden Rules 注入是极轻量操作（预期 < 30 行），每次会话都执行
+- 蒸馏提醒按需触发，只在条件满足时提醒
+- problems.md 的详细记录**不主动读取**，仅在操作 A/B/C 时按需读取
+- 本 Rule 只负责触发和注入，具体操作流程由 `problem-distillery` Skill 定义

.claude/rules/common/epee-orchestrator.md

@@ -0,0 +1,63 @@
+## EPEE Skill Orchestrator — 触发雷达
+
+### 被动检测
+
+Agent 在制定方案或执行任务过程中，如果发现当前任务符合以下**任意一条**特征，
+必须读取 `epee-orchestrator` Skill 的 SKILL.md 并执行其分流流程：
+
+1. **手动配置密集**：任务需要用户在 IDE 或工具中进行大量手动配置
+   （如批量填写配置字段、逐一调整参数等）
+2. **重复模式明确**：同类操作预计会反复出现（如批量创建同结构的配置文件、
+   批量设置同类模块等）
+3. **手工指引过长**：Agent 发现自己正在生成超过 10 步的"手动操作步骤"
+   而非直接产出代码或配置文件
+
+### Registry 同步（强制）
+
+每次**创建**或**修改**任何 Skill（包括 SKILL.md 内容变更、新增 Skill 等）后，
+Agent **必须**执行以下操作：
+
+1. 读取 `epee-orchestrator` Skill 目录下的 `registry.md`
+2. 更新或新增对应 Skill 的条目（格式参见 registry.md 中的条目结构）
+3. 确保条目中的能力描述和触发场景与 Skill 实际内容一致
+
+> **注意**：此项已纳入 `changelog-recall.md` 的"任务完成 Checklist"第 3 项。
+> 如果 Agent 在 checklist 阶段发现遗漏，必须立即补执行。
+
+### Skill 自迭代（强制）
+
+每个 SKILL.md 必须包含一个"自迭代日志"章节，用于记录使用该 Skill 过程中发现的经验教训。
+
+**触发条件** — 在创建或使用任何 Skill 时，遇到以下情况应触发自迭代流程：
+
+1. 因信息缺失导致生成结果错误或构建失败
+2. 用户需要反复补充同类信息
+3. 生成产物与用户预期存在系统性偏差
+
+> **注意**：此项已纳入 `changelog-recall.md` 的"任务完成 Checklist"第 4 项。
+> Agent 不应等到"下次使用 Skill 时"才想起自迭代——当次就应检查。
+
+**流程**：
+
+1. 识别问题根因，归纳为一条简明的检查项
+2. 向用户确认："是否要将此项记录到该 Skill 的自迭代日志中？"
+3. 用户同意后，追加到对应 SKILL.md 的"已知必要检查"列表
+4. 后续使用该 Skill 时，必须遵守日志中已记录的所有检查项
+
+**SKILL.md 中的格式**：
+
+```markdown
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+1. **检查项名称** — 简要说明原因和应对方式。
+```
+
+**原则**：
+
+- 每条检查项应当**具体可执行**，而非泛泛的提醒
+- 检查项只增不删，除非用户明确要求移除
+- 新建 Skill 时须预置空的自迭代日志章节

.claude/rules/common/pitfall-recall.md

@@ -0,0 +1,31 @@
+## 踩坑经验自动检索
+
+### 被动检测触发
+
+Agent 在以下场景中，应自动读取 `.claude/pitfalls/pitfalls.md` 并进行匹配检索：
+
+1. **进入 Debug mode**：读取全部条目，将当前错误症状与已有记录比对
+2. **遇到运行时错误**：提取错误信息关键词，在"症状"字段中检索匹配
+3. **同一问题第二次出现**：如果当前会话中某个错误已出现过一次且未解决，强制检索
+
+### 匹配策略
+
+```
+1. 提取当前问题的信号：错误信息关键词、涉及文件/模块、技术栈
+2. 在 pitfalls.md 中匹配：
+   - 硬匹配：错误关键词出现在条目的"症状"中
+   - 软匹配：模块/技术栈出现在条目的"关联"中
+3. 命中时在分析开头提示：
+   > 注意：之前遇到过类似问题 [PF-xxx]：[标题]。根因是 [xxx]，先排查这个方向。
+```
+
+### 写入提醒
+
+Agent 在完成涉及 debug/修复的任务后，应读取 `pitfall-journal` Skill 并执行其"操作 A：写入记录"流程。
+判断标准：问题的根因是否"非显而易见"——如果只看代码逻辑觉得应该没问题，但实际运行时才暴露，就值得记录。
+
+### 注意
+
+- 检索结果是**辅助参考**，不是确定性答案——匹配到不代表根因一定相同
+- pitfalls.md 不存在时跳过，不报错
+- 每次会话中对同一条 pitfall 最多提醒一次

.claude/rules/common/profile-recall.md

@@ -0,0 +1,42 @@
+## 画像上下文注入
+
+每次会话处理用户第一个任务前，执行以下操作：
+
+### 用户画像注入
+
+1. 读取 `~/.claude/profile/user-profile.md`（不存在则跳过）
+2. 如文件存在且有实质内容（不仅是分类标题），将全部条目作为背景知识注入上下文
+3. 这些信息帮助 Agent 理解用户的偏好、风格和决策倾向
+4. 在后续回复中自然融入，不显式提及"根据画像"
+
+### 项目画像注入
+
+1. 读取 `.claude/profile/project-profile.md`（不存在则跳过）
+2. 如文件存在且有实质内容，将全部条目作为背景知识注入上下文
+3. 这些信息帮助 Agent 理解项目的定位、技术栈和设计约定
+4. 在后续回复中自然融入，不显式提及"根据画像"
+
+### 逐级上溯
+
+当某条画像记录**语义模糊**（无法判断偏好的具体适用场景、与当前任务的关系不明确），执行以下查找：
+
+```
+1. 从精简版条目中提取锚点 ID（HTML 注释中的 PF-xxx）
+2. 在对应的 Log 文件中 Grep 该 ID
+   - 用户画像 → ~/.claude/profile/user-profile-log.md
+   - 项目画像 → .claude/profile/project-profile-log.md
+3. 找到 → 用 Read 工具读取该 ID 所在行号 ±15 行范围（精准读取，不读全文）
+4. Log 中包含原始上下文、来源对话等完整信息，通常足以消除歧义
+```
+
+### 上溯原则
+
+- **按需触发**：只有在精简版信息不足以支撑当前判断时才上溯
+- **精准读取**：通过 Grep 定位行号 + Read 局部读取，禁止全文读取 Log
+- **最小化**：一次上溯通常只涉及 1-2 条记录
+
+### 注意
+
+- 画像注入是低成本操作（预期 < 30 行），每次会话都执行
+- 画像的写入和管理由 `profile-memory` Skill 负责，本 Rule 只负责读取和注入
+- 不存在画像文件时不报错，直接跳过