🧠 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 项目结构扫描#

text

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 项目:

text

Grep "^export (class|function|const|interface|type|enum)" --type ts,tsx,js,jsx

Python 项目:

text

Grep "^(class |def )" --type py

Go 项目:

text

Grep "^(func |type .* struct)" --type go

Rust 项目:

text

Grep "^(pub fn |pub struct |pub enum |pub trait )" --type rs

Java/Kotlin 项目:

text

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": "<npm|yarn|pnpm|pip|cargo|go modules|...>"
  },

  "techStack": {
    "language": "<主要语言及版本>",
    "framework": "<主要框架及版本>",
    "buildTool": "<构建工具>",
    "runtime": "<运行时环境>",
    "uiLibrary": "<UI 库（如适用）>",
    "testFramework": "<测试框架>"
  },

  "packages": {
    "<包名>": {
      "path": "<路径>",
      "role": "<职责描述>",
      "entry": "<入口文件>",
      "format": "<ESM|CJS|mixed>"
    }
  },

  "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": "<TypeScript (strict)|Python 3.x|Go|...>",
    "indent": "<2 spaces|4 spaces|tabs>",
    "quotes": "<single|double>",
    "semicolons": "<true|false|N/A>",
    "trailingComma": "<none|es5|all|N/A>",
    "formatter": "<Prettier|Black|gofmt|rustfmt|...>",
    "linter": "<ESLint|Ruff|golint|clippy|...>"
  },

  "namingConventions": {
    "files": { "<类型>": "<命名规则>" },
    "code": {
      "classes": "<PascalCase>",
      "interfaces": "<规则>",
      "functions": "<camelCase|snake_case>",
      "constants": "<UPPER_SNAKE_CASE>",
      "variables": "<camelCase|snake_case>"
    }
  },

  "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#

要注入的记忆系统指令块#

以下内容用 <!-- MEMORY-SYSTEM-START --> 和 <!-- MEMORY-SYSTEM-END --> 标记包裹:

markdown

<!-- MEMORY-SYSTEM-START -->
## 📖 启动时只读一个文件

\```
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 不需要"记住一切"，只需要"知道去哪找"。

text

### 注入逻辑

1. **如果 CLAUDE.md 不存在**:
   创建新文件，内容为:
   ```markdown
   # <项目名> — Claude 工程指令

   > 记忆系统 v3.0 — "搜索引擎"模型：启动只读摘要，详情按需检索

   <记忆系统指令块>

1. 如果 CLAUDE.md 已存在:

   • 如果已包含 <!-- MEMORY-SYSTEM-START --> 标记，替换标记之间的内容
   • 如果不包含标记，在文件 顶部第一个一级标题之后 插入记忆系统指令块
   • 保留 CLAUDE.md 中的所有其他内容不变

---

Step 4: 输出完成报告#

扫描创建的所有文件，统计大小，输出如下格式的报告:

text

✅ 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 规则）