--- name: init-memory description: 为任意项目初始化 Claude 持久化记忆系统（v3.0 搜索引擎模型）。自动扫描项目结构、技术栈、代码规范，生成完整的记忆文件和 CLAUDE.md 指令。 --- # 🧠 Claude 持久化记忆系统初始化 Skill > 记忆系统 v3.0 — "搜索引擎"模型：启动只读摘要，详情按需检索 > > **核心理念**: Claude 不需要"记住一切"，只需要"知道去哪找"。 ## 参数处理 用户输入参数: $ARGUMENTS 解析参数: - `--force`: 覆盖已有的记忆文件（默认跳过已存在的文件） - `--minimal`: 只创建核心文件（SUMMARY.md, architecture.json, conventions.json, semantic-index.json, changelog.json） - `--lang zh`: 注释和描述使用中文（默认） - `--lang en`: 注释和描述使用英文 如果 `.claude/memory/SUMMARY.md` 已存在且没有 `--force` 参数，**停止执行**并提示用户: > ⚠️ 记忆系统已存在。使用 `--force` 覆盖，或手动删除 `.claude/memory/` 目录后重试。 --- ## Step 1: 扫描项目 ### 1.1 项目结构扫描 ``` Glob "**/{package.json,tsconfig.json,Cargo.toml,go.mod,pyproject.toml,setup.py,requirements.txt,pom.xml,build.gradle,Gemfile,composer.json,CMakeLists.txt,Makefile,.csproj,pubspec.yaml,mix.exs,deno.json}" (忽略 node_modules、vendor、target、dist、build、.git) ``` 读取找到的配置文件，提取: - 项目名称（优先: package.json name > Cargo.toml name > go.mod module > 目录名） - 技术栈（语言、框架、构建工具、运行时） - 依赖列表（核心依赖，不含 devDependencies 细节） - 脚本/命令（build/test/dev/start） - 是否为 monorepo（workspaces / 多个子 package.json） ### 1.2 目录布局 ```bash find . -maxdepth 3 -type d \ ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \ ! -path '*/build/*' ! -path '*/.next/*' ! -path '*/target/*' \ ! -path '*/vendor/*' ! -path '*/__pycache__/*' ! -path '*/.claude/*' \ ! -path '*/.venv/*' ! -path '*/venv/*' ! -path '*/.tox/*' \ | head -80 | sort ``` ### 1.3 核心模块识别 根据项目语言类型选择合适的扫描模式: **TypeScript/JavaScript 项目:** ``` Grep "^export (class|function|const|interface|type|enum)" --type ts,tsx,js,jsx ``` **Python 项目:** ``` Grep "^(class |def )" --type py ``` **Go 项目:** ``` Grep "^(func |type .* struct)" --type go ``` **Rust 项目:** ``` Grep "^(pub fn |pub struct |pub enum |pub trait )" --type rs ``` **Java/Kotlin 项目:** ``` Grep "^(public class|public interface|public enum|class |fun )" --type java,kt ``` 取前 100 个结果，识别核心模块和它们的位置。 ### 1.4 大文件识别（热点文件） ```bash find . \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \ -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.java' \ -o -name '*.kt' -o -name '*.vue' -o -name '*.svelte' -o -name '*.rb' \ -o -name '*.ex' -o -name '*.exs' -o -name '*.dart' -o -name '*.swift' \ -o -name '*.cpp' -o -name '*.c' -o -name '*.h' \) \ ! -path '*/node_modules/*' ! -path '*/dist/*' ! -path '*/build/*' \ ! -path '*/target/*' ! -path '*/vendor/*' ! -path '*/.git/*' \ -exec wc -l {} + 2>/dev/null | sort -rn | head -20 ``` 对超过 500 行的文件进行逻辑分区扫描（扫描 function/class/section 定义及其行号）。 如果项目源文件较少，可降低阈值到 300 行。 ### 1.5 代码规范推断 读取 3-5 个核心源文件的前 50 行，推断: - 缩进风格（tab vs space，几个空格） - 引号风格（单引号 vs 双引号） - 分号使用 - 命名约定（camelCase / snake_case / PascalCase） - 导入风格和顺序 - 注释语言（中文/英文/混合） 同时检查是否存在以下配置文件: `.eslintrc*`, `.prettierrc*`, `rustfmt.toml`, `.editorconfig`, `pyproject.toml [tool.black]`, `setup.cfg [flake8]`, `.rubocop.yml`, `biome.json` ### 1.6 项目特有规则扫描 检查是否已有: - `CLAUDE.md` — 已有的 Claude 指令 - `.claude/` 目录 — 已有的 Claude 配置 - `CONTRIBUTING.md` — 贡献指南中的规范 - `.github/` — CI/CD 配置中的约束 --- ## Step 2: 创建记忆文件 创建 `.claude/memory/` 目录，然后基于 Step 1 的扫描结果创建以下文件。 **重要规则**: - 所有 JSON 文件中的 `$schema` 字段使用实际项目名称（从配置文件推断），不要硬编码 - 所有内容必须来自实际扫描，不得使用占位模板 - JSON 使用 2 空格缩进 - 日期格式统一 YYYY-MM-DD - 文件使用 UTF-8 编码 ### 2.1 architecture.json — 项目架构概览 ```json { "$schema": "<项目名> Architecture", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "项目架构概览", "project": { "name": "<项目名>", "description": "<从配置文件推断的项目描述>", "monorepo": false, "packageManager": "" }, "techStack": { "language": "<主要语言及版本>", "framework": "<主要框架及版本>", "buildTool": "<构建工具>", "runtime": "<运行时环境>", "uiLibrary": "", "testFramework": "<测试框架>" }, "packages": { "<包名>": { "path": "<路径>", "role": "<职责描述>", "entry": "<入口文件>", "format": "" } }, "mainModules": { "<模块名>": { "file": "<文件路径>", "lines": "<行数>", "role": "<职责描述>", "warning": "<注意事项（可选）>", "keyDataStructures": ["<核心数据结构>"] } }, "keyDependencies": [ { "name": "<包名>", "version": "<版本>", "purpose": "<用途>" } ] } ``` **monorepo 项目**: `packages` 字段列出所有子包及其角色。 **单包项目**: `packages` 只有一个条目或省略。 ### 2.2 conventions.json — 代码规范 ```json { "$schema": "<项目名> Code Conventions", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "代码规范和约定。新增代码必须遵守这些规范", "codeStyle": { "language": "", "indent": "<2 spaces|4 spaces|tabs>", "quotes": "", "semicolons": "", "trailingComma": "", "formatter": "", "linter": "" }, "namingConventions": { "files": { "<类型>": "<命名规则>" }, "code": { "classes": "", "interfaces": "<规则>", "functions": "", "constants": "", "variables": "" } }, "patterns": { "<模式名>": { "description": "<描述>", "template": "<代码模板（可选）>", "steps": ["<步骤>"] } }, "commitMessageStyle": { "language": "<项目注释语言>", "prefix": "feat:/fix:/refactor:/chore:/docs:/test:", "examples": ["<示例>"] }, "importOrder": ["<导入分组规则>"], "criticalRules": [ "<从代码和配置中推断出的关键规则>" ] } ``` ### 2.3 semantic-index.json — 语义索引 ```json { "$schema": "<项目名> Semantic Index", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "关键词索引——从功能域/关键词到相关文件的映射", "index": { "<关键词|别名|同义词>": { "description": "<功能域描述>", "files": [ { "path": "<文件路径>", "sections": ["<逻辑区域>"], "lineRange": [0, 0] } ], "quickRules": ["<该领域的快速提示/规则>"] } } } ``` 基于 Step 1.3 的扫描结果填充。将相关的导出按功能域分组。 每个索引条目可以有多个关键词别名（用 `|` 分隔）。 ### 2.4 hotspot-map.json — 热点文件分区图 ```json { "$schema": "<项目名> Hotspot Map", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "热点文件的逻辑分区图。修改大文件前先查此文件定位行号范围", "files": { "<文件名>": { "path": "<完整相对路径>", "totalLines": 0, "touchFrequency": 0, "sections": [ { "name": "<逻辑分区名>", "lineRange": [0, 0], "description": "<该分区的功能描述>", "keySymbols": ["<重要函数/类名>"], "touchCount": 0, "subSections": [] } ] } } } ``` 仅包含超过 500 行（小项目 300 行）的文件。每个文件最多 15 个分区。 ### 2.5 task-context.json — 任务上下文 ```json { "$schema": "<项目名> Task Context", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "当前任务上下文。帮助 Claude 理解未完成的工作", "currentTasks": [], "recentCompleted": [], "pendingIssues": [], "completedTasks": [], "knownLimitations": [] } ``` ### 2.6 changelog.json — 变更日志 ```json { "$schema": "<项目名> Session Changelog", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "增量变更日志。每次会话修改代码后追加记录", "sessions": [ { "id": "SESSION-001", "date": "<今天日期>", "summary": "初始化 Claude 记忆系统", "changes": [ { "action": "create", "files": [".claude/memory/*", "CLAUDE.md"], "reason": "建立持久化记忆系统，实现跨会话知识保持" } ], "decisions": ["采用 v3.0 搜索引擎模型：启动只读 SUMMARY.md，详情按需 Grep 检索"], "lessonsLearned": [], "ripples": { "description": "纯新增文件，无代码影响", "affectedModules": [], "sideEffects": [] }, "rejectedAlternatives": [] } ] } ``` ### 2.7 bugs-and-fixes.json — Bug 记录 ```json { "$schema": "<项目名> Bug & Fix Registry", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "已知 Bug 和修复记录。避免相同问题重复犯错", "bugs": [], "commonMistakes": [], "predictions": [] } ``` ### 2.8 causality-graph.json — 因果图谱 ```json { "$schema": "<项目名> Causality Graph", "$version": "1.0.0", "$updated": "<今天日期>", "$description": "因果图谱——记录 Bug 的完整因果链。新 Bug 出现时沿已知链反向推导", "chains": [], "chainIndex": {} } ``` **如果使用了 `--minimal` 参数**，跳过: hotspot-map.json, task-context.json, bugs-and-fixes.json, causality-graph.json ### 2.9 SUMMARY.md（最后创建） ```markdown # <项目名> — Claude 记忆摘要 > 记忆系统 v3.0 — 本文件是固定大小的"缓存"，详细数据在各 JSON 文件中 ## 🏗️ 架构速览 - **技术栈**: <语言 + 框架 + 构建工具> - **项目结构**: <简要描述目录布局> - **核心模块**: <列出 3-5 个最重要的模块> ## 📊 热点文件 <列出行数最多的 3-5 个文件及其行数> ## 🔄 最近 3 次变更 1. SESSION-001: 初始化 Claude 记忆系统 ## 📋 当前状态 - **进行中**: 无 - **待处理**: 无 ## ⚠️ 高频陷阱（Top 5） 暂无记录 ## 🔍 检索指南 | 需要什么 | 怎么查 | |----------|--------| | 功能域→文件映射 | `Grep "关键词" .claude/memory/semantic-index.json` | | 大文件行号定位 | `Grep "section名" .claude/memory/hotspot-map.json` | | Bug 因果链 | `Grep "症状" .claude/memory/causality-graph.json` | | 已知 Bug/预判 | `Grep "症状" .claude/memory/bugs-and-fixes.json` | | 历史决策 | `Grep "功能" .claude/memory/changelog.json` | | 代码规范 | `Read .claude/memory/conventions.json` | | 完整架构 | `Read .claude/memory/architecture.json` | ``` --- ## Step 3: 生成/更新 CLAUDE.md ### 要注入的记忆系统指令块 以下内容用 `` 和 `` 标记包裹: ```markdown ## 📖 启动时只读一个文件 \``` Read .claude/memory/SUMMARY.md \``` **不要**在启动时读取其他记忆文件。SUMMARY.md 包含架构速览、当前状态、高频陷阱和检索指南。 ## 🔍 按需检索（改代码/修 Bug 前查询） 需要详情时，用 Grep/Read **精准查询**对应文件，不要全量加载： | 场景 | 做什么 | |------|--------| | **改代码前** — 定位文件和行号 | `Grep "关键词" .claude/memory/semantic-index.json` | | **改核心文件** — 查逻辑分区行号 | `Grep "section名" .claude/memory/hotspot-map.json` | | **修 Bug 前** — 匹配已知症状 | `Grep "症状关键词" .claude/memory/causality-graph.json` | | **修 Bug 前** — 查是否已预判 | `Grep "症状" .claude/memory/bugs-and-fixes.json` | | **查历史决策** — 为什么这样做 | `Grep "功能关键词" .claude/memory/changelog.json` | | **查代码规范** — 命名/风格/模式 | `Read .claude/memory/conventions.json` | | **查完整架构** — 模块/IPC/技术栈 | `Read .claude/memory/architecture.json` | ## ⚡ 关键规则 > 以下规则从项目扫描中自动生成，请根据实际情况补充 1. **热点文件** — 修改超过 500 行的文件前，必须先 Grep semantic-index + hotspot-map 定位 2. **修 Bug** — 先 Grep causality-graph 的 chainIndex 匹配症状 3. 提交信息推荐 `feat:/fix:/refactor:/chore:` 前缀 ## 🔄 任务完成后必须更新 每次完成代码修改后，按需更新以下文件（只更新涉及到的）： ### 必更新 - **changelog.json** — 在 `sessions` 数组末尾追加： ```json { "id": "SESSION-xxx", "date": "YYYY-MM-DD", "summary": "...", "changes": [{ "action": "create|modify|delete", "files": [...], "reason": "..." }], "decisions": [...], "lessonsLearned": [...], "ripples": { "description": "...", "affectedModules": [...], "sideEffects": [...] }, "rejectedAlternatives": [{ "option": "...", "reason": "..." }] } ``` ### 按需更新 - **bugs-and-fixes.json** — 修了 Bug → 追加 bugs；发现易错模式 → 追加 commonMistakes；主动扫描 → 追加 predictions - **task-context.json** — 更新 currentTasks / recentCompleted（只保留最近 5 条）/ pendingIssues - **hotspot-map.json** — 改了核心文件 → touchCount +1, lastModified, lineRange 偏移 - **semantic-index.json** — 新增功能域 → 添加索引条目 - **causality-graph.json** — 发现新因果链 → 追加 chains + 更新 chainIndex - **architecture.json** — 架构变化（新模块/IPC/页面）→ 同步更新 ### 最后一步：重写 SUMMARY.md 从各详细文件中提取最新信息，**重写**（非追加）SUMMARY.md： - `最近 3 次变更` ← changelog.json 最后 3 条的 summary - `当前状态` ← task-context.json 的 currentTasks + pendingIssues - `高频陷阱` ← bugs-and-fixes.json 的 commonMistakes（Top 5） - 其他部分按需更新 > 💡 设计理念：SUMMARY.md 是固定大小的"缓存"，详细数据永远保留在原文件中。 > Claude 不需要"记住一切"，只需要"知道去哪找"。 ``` ### 注入逻辑 1. **如果 CLAUDE.md 不存在**: 创建新文件，内容为: ```markdown # <项目名> — Claude 工程指令 > 记忆系统 v3.0 — "搜索引擎"模型：启动只读摘要，详情按需检索 <记忆系统指令块> ``` 2. **如果 CLAUDE.md 已存在**: - 如果已包含 `` 标记，替换标记之间的内容 - 如果不包含标记，在文件**顶部第一个一级标题之后**插入记忆系统指令块 - **保留 CLAUDE.md 中的所有其他内容不变** --- ## Step 4: 输出完成报告 扫描创建的所有文件，统计大小，输出如下格式的报告: ``` ✅ Claude 记忆系统初始化完成！ 📁 创建的文件: .claude/memory/SUMMARY.md (xxx bytes) .claude/memory/architecture.json (xxx bytes) .claude/memory/conventions.json (xxx bytes) .claude/memory/semantic-index.json (xxx bytes) .claude/memory/hotspot-map.json (xxx bytes) .claude/memory/task-context.json (xxx bytes) .claude/memory/changelog.json (xxx bytes) .claude/memory/bugs-and-fixes.json (xxx bytes) .claude/memory/causality-graph.json(xxx bytes) CLAUDE.md (已更新/已创建) 📊 项目分析摘要: - 技术栈: <语言> + <框架> - 核心模块: <数量>个 - 热点文件(>500行): <数量>个 - 语义索引域: <数量>个 🧠 记忆系统设计: - 启动加载: ~3KB（仅 SUMMARY.md） - 详情存储: 按需 Grep 检索 - 增长模型: 启动负载永远 O(1) 💡 下一步建议: 1. 审查 architecture.json 中的模块描述是否准确 2. 检查 conventions.json 是否符合团队规范 3. 在 task-context.json 中添加当前进行中的任务 4. 将 .claude/memory/ 加入版本控制（推荐） 5. 根据项目特点补充 CLAUDE.md 中的关键规则 ``` --- ## 注意事项 - 所有文件使用 UTF-8 编码 - JSON 文件使用 2 空格缩进 - 日期格式统一使用 YYYY-MM-DD - **不要在任何文件中使用占位模板**——所有内容必须来自实际扫描 - 如果某个扫描步骤失败（比如没有 package.json），优雅降级，用目录名作为项目名 - 热点文件扫描如果源文件不多，可以降低阈值到 300 行 - 如果项目已有 CLAUDE.md 中的项目特有规则（如 IPC 规则、弹窗规则等），注入时保留这些规则 - 对于不同技术栈的项目，`关键规则` 部分应自适应生成（如 Go 项目不需要 IPC 规则）