MistPrism SOP

Claude Code 记忆系统设计与项目治理实战

11分钟阅读

背景

GoDreamAI 项目积累了 60+ 文档散落在 docs/ 根目录，CLAUDE.md 塞了过多模块细节，记忆系统没有分层设计。一次完整的系统优化，覆盖了记忆架构、文档治理、工作流自动化三个维度。

三层记忆架构

Claude Code 的上下文注入机制决定了记忆系统的分层设计：

层文件加载方式放什么
全局约束CLAUDE.md每次会话自动加载架构概览、关键约束、常用命令（< 500 行）
路径感知.claude/rules/*.md编辑匹配路径的文件时加载模块级规则（线程模型、Provider 模式等）
文档索引docs/INDEX.md通过 @import 注入 CLAUDE.md活跃文档路由表

关键机制

@import 是 EAGER 加载：@docs/INDEX.md 写在 CLAUDE.md 里，内容在会话启动时就注入系统提示词，占用每次请求的上下文。所以只 @import 精简的索引（19 行），不 @import 大文件。

rules/ 的 paths 字段：YAML frontmatter 里声明 paths:，只在 Claude 读写匹配路径的文件时自动加载。

---
paths:
  - "modules/**"
---
# 模块层规则
- 单例表、线程模型、Provider/Strategy 模式...

MEMORY.md 200 行限制：~/.claude/projects/.../memory/MEMORY.md 只有前 200 行被注入上下文。超出的内容不会被读取。官方不提供自动清理，需要手动维护。

设计陷阱

规则放错位置 = 规则不存在

把 main.py 的启动流程约束放在 rules/ui.md（paths: components/**）里，编辑 main.py 时不会加载这条规则。全局约束必须放在 CLAUDE.md。

判断原则：这条规则在哪些文件被编辑时需要生效？ 如果答案是”任何文件”或”不确定”，放 CLAUDE.md。如果是特定目录，放 rules/。

文档治理

归档策略

按项目阶段（phase）分类，不按月份：

docs/
├── INDEX.md              ← 活跃文档索引（@import 进 CLAUDE.md）
├── plans/                ← 实施计划（永久保留，日期前缀排序）
├── design/               ← 架构设计
├── reference/            ← 参考手册
├── api/                  ← API 文档
└── archive/
    ├── INDEX.md          ← 归档索引（NOT @imported，按需读取）
    ├── phase-01-foundation/
    ├── phase-02-storage-rebuild/
    └── ...

生命周期规则

  • plans/ 文件永久保留，不移动（完成后可能还要回溯）
  • 归档季度集中处理，不强制每次任务后执行
  • 临时调试记录、AI 提示词不保存进 docs/
  • archive/INDEX.md 提供一行摘要索引，Claude 需要历史背景时自行查阅

为什么 plans/ 不移到 archive？

如果完成后立即归档，发现 bug 需要回溯时又要移回来——这个闭环是错的。靠日期前缀自然排序，旧计划自己沉底。

工作流 Skills

/go — 开发全流程编排

把反复出现的开发指令模式（“先看 git status，再读代码，再写计划…“）封装为一条命令。设计为”路由表”而非”操作手册”——只列阶段和对应的 skill，具体怎么做由 skill 自己定义。

Phase做什么对应 Skill
0. Context Syncgit status + 重读配置—
1. Research读代码和文档brainstorming
2. Plan产出实施计划writing-plans
3. Execute分批执行executing-plans
4. Verify验证无崩溃verification-before-completion
5. Handback报告交付requesting-code-review

Skill 的粒度

最初 /go 写了 91 行，把每个阶段的操作都展开写。精简到 35 行的路由表后效果更好——skill 应该是指令编排器，不是操作手册。

/audit — 结构化评估审计

从用户高频指令模式中提取：每次说”评估一下”都需要同样的结构（评分维度 → 问题清单 → 修复建议）。

支持四种 scope：

  • 文件路径 → 审计代码质量
  • 目录路径 → 审计结构合理性
  • memory → 审计记忆系统
  • 不指定 → 审计最近一次 git 改动

评分用三级：✅ 合理 / ⚠️ 可改进 / ❌ 需修复。

/commit — 标准化提交

自动执行：安全检查（敏感文件、合并冲突）→ 分支保护 → 代码审查 → 生成 Conventional Commits 中文信息 → 用户确认。

Hooks 自动化

SessionStart: MEMORY.md 行数检查

在 ~/.claude/settings.json 注册 SessionStart hook，每次会话启动时扫描所有项目的 MEMORY.md：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/check-memory-size.sh"
          }
        ]
      }
    ]
  }
}

脚本逻辑：遍历 ~/.claude/projects/*/memory/MEMORY.md，超过 150 行的输出警告。stdout 会注入到 Claude 上下文，Claude 会提醒用户清理。

Hook 输出机制

SessionStart hook 的 stdout（exit 0）会被注入为系统消息。无输出 = 静默通过。这意味着脚本只需要在有问题时输出，正常情况下保持安静。

维护节奏

频率动作
每次会话Hook 自动检查 MEMORY.md 行数
每月一次手动审视 MEMORY.md，删除过时条目
每季度docs/ 归档整理，旧文档移入 archive/ 对应 phase

与官方文档的对比验证

以下每项设计决策均对照官方文档验证。

CLAUDE.md 内容管理

维度官方说法我们的做法对齐
大小”Bloated CLAUDE.md files cause Claude to ignore your actual instructions” — 没给具体行数，但强调精简~70 行✅
放什么项目特有的架构决策、非显而易见的约定、常用命令架构概览 + 关键约束 + 常用命令✅
不放什么”Anything Claude can figure out by reading code”、详细 API 文档、文件逐一描述模块细节移到 rules/，API 文档指向 docs/api/✅

官方原文

“Keep it concise. For each line, ask: ‘Would removing this cause Claude to make mistakes?’ If not, cut it.”

— Memory - Claude Code Docs

@import 加载行为

维度官方说法我们的做法对齐
父目录 CLAUDE.md”loaded in full at launch”项目根 CLAUDE.md 启动时全量加载✅
子目录 CLAUDE.md”load on demand when Claude reads files in those directories”modules/seedream/CLAUDE.md 按需加载✅
@import 递归最大 5 hops只用 1 层（CLAUDE.md → INDEX.md）✅
代码块内import 在 code span/block 内不解析——

官方原文

“CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in child directories load on demand when Claude reads files in those directories.”

— Memory - Claude Code Docs

rules/ 路径感知机制

维度官方说法我们的做法对齐
格式YAML frontmatter paths: + globpaths: ["modules/**"]✅
无 paths 字段无条件加载（always applies）有明确 paths 的才创建 rule 文件✅
发现方式递归扫描 .claude/rules/ 下所有 .md扁平放置（modules.md, ui.md）✅
用户级~/.claude/rules/ 在项目规则之前加载未使用（全局规则放 CLAUDE.md）✅

官方示例 

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation

— Memory - Claude Code Docs

MEMORY.md 自动记忆

维度官方说法我们的做法对齐
注入量”The first 200 lines of MEMORY.md are loaded into Claude’s system prompt”保持 57 行（远低于限制）✅
超出部分”Content beyond 200 lines is not loaded automatically”——
Topic 文件详细笔记移到独立 .md，按需读取MEMORY.md 作精简索引✅
自动清理官方不提供，仅 /memory 手动命令Hook 提醒 + 手动清理✅
关闭方式autoMemoryEnabled: false 或 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1保持开启✅

官方原文

“Claude is instructed to keep it concise by moving detailed notes into separate topic files.”

— Memory - Claude Code Docs

SessionStart Hook

维度官方说法我们的做法对齐
stdout 行为”Any text your hook script prints to stdout is added as context for Claude”超限时输出警告文本✅
阻止能力SessionStart exit code 2 只显示 stderr，无法阻止启动exit 0（非阻塞）✅
Matcherstartup / resume / clear / compact"" 匹配所有✅
环境变量注入CLAUDE_ENV_FILE 仅 SessionStart 可用未使用—

官方 Matcher 表

MatcherWhen it fires
startupNew session
resume--resume, --continue, or /resume
clear/clear
compactAuto or manual compaction

— Hooks - Claude Code Docs

官方文档索引

主题URL
记忆系统总览code.claude.com/docs/en/memory
Hooks 指南code.claude.com/docs/en/hooks
最佳实践code.claude.com/docs/en/best-practices

关键收获

  1. @import 不是免费的：每个 @import 的内容都占用每次请求的上下文窗口，只 import 真正需要每次都看的内容
  2. rules/ 路径匹配是精确的：全局约束别放进路径感知的 rules 文件，否则在关键场景不会加载
  3. Skill 是路由表不是手册：编排器只负责调度，具体操作交给专业 skill
  4. Plan 不要急着归档：完成 ≠ 不再需要，靠日期前缀自然排序
  5. 官方没有自动清理记忆：这是有意设计，误删比冗余代价更高，用 hook 提醒 + 手动清理是最佳实践

关系图谱