context-manager

上下文管理器

管理 Claude Code 记忆层级，并审查项目中所有 Markdown 文件。生成组织良好的记忆文件，检测文档重叠，并报告上下文总占用量。

四个上下文层

层级	位置	用途	此技能的作用
记忆	./CLAUDE.md、子目录、.claude/rules/*.md	项目上下文、命令、架构、规则	审查、评分、维护
项目文档	ARCHITECTURE.md、DATABASE_SCHEMA.md、API_ENDPOINTS.md、docs/**/*.md	技术文档	根据项目类型检查文件是否存在、标记过时内容、检测与 CLAUDE.md 的重叠
会话	SESSION.md、PROJECT_BRIEF.md	临时进度跟踪	报告是否存在及文件大小（由 dev-session 管理）
公开文档	README.md、CONTRIBUTING.md、其他根目录 .md 文件	面向公众的文档	检测与 CLAUDE.md 的重复内容

也会扫描自动记忆（~/.claude/projects/*/memory/MEMORY.md）以供参考，但由 Claude 自动管理。

操作模式

模式 1：会话记录

适用时机：会话结束时、“记录经验”、“根据我们的发现更新 CLAUDE.md”

1. 回顾对话，找出值得保留的发现：
   • 有效（或无效）的命令
   • 发现的问题及解决方法
   • 已作出的架构决策
   • 发现的配置细节
   • 有助于后续会话的模式
2. 使用下方的归类决策树为每项发现分类
3. 将所有更改汇总为一组差异
4. 提交这批更改，并在获得一次是/否确认后应用

保持简洁：每个概念一行。不要冗长解释，也不要提供泛泛的建议。

模式 2：完整审查

适用时机：“审查上下文”、“审查记忆”、“检查项目文档”、定期维护，或在长期未维护的项目中工作时

1. 运行审查脚本：

   python3 plugins/dev-tools/skills/context-manager/scripts/audit_memory.py [repo-path]
   

2. 检查输出：
   • 记忆层：CLAUDE.md 文件大小、质量评分、规则文件大小
   • 项目文档：是否存在、是否过时、与 CLAUDE.md 的重叠
   • 会话/公开文档：是否存在及文件大小
   • Markdown 占用量：按层统计的总 KB 数
   • 重叠警告：不同文件间重复的章节
3. 自主生成更改——按需创建、更新或标记文件
4. 将所有更改汇总为一批，供用户批准
5. 应用已批准的更改
6. 检查是否已安装提交记录钩子；如果没有，则主动提出安装（参见 references/commit-hook.md）

对于大型仓库，委派给子 Agent：

Task(subagent_type: "general-purpose",
  prompt: "Run python3 plugins/dev-tools/skills/context-manager/scripts/audit_memory.py /path/to/repo
           and summarise the findings.")

模式 3：重构

适用时机：“重构记忆”、根目录 CLAUDE.md 超过 200 行，或首次设置记忆时

1. 先执行完整审查（模式 2）
2. 拆分过大的文件：
   • 将根目录 CLAUDE.md 中的主题章节提取到 .claude/rules/<topic>.md
   • 将目录专属内容提取到子目录中的 CLAUDE.md 文件
   • 如果详细技术内容属于参考资料而非操作上下文，则从 CLAUDE.md 移至 docs/ 或 ARCHITECTURE.md
3. 解决内容重叠：如果 CLAUDE.md 与 ARCHITECTURE.md 或 docs/ 有重复内容，则删除重复部分
4. 根据项目类型创建缺失的文档文件
5. 提交重构计划，并在获得批准后执行

归类决策树

Would this still apply if I switched to a completely different project?
├── YES → ~/.claude/rules/<topic>.md
│         (correction rules, API patterns, coding standards)
└── NO  → Is it specific to a subdirectory?
    ├── YES → <dir>/CLAUDE.md
    │         (integrations, directory-specific gotchas)
    └── NO  → Is it reference documentation or operational context?
        ├── Reference → ARCHITECTURE.md or docs/
        │               (system design, schemas, detailed flows)
        └── Operational → ./CLAUDE.md (project root)
                          (identity, stack, commands, critical rules)

大小目标

文件类型	目标	最大值
根目录 CLAUDE.md	50-150 行	200
子目录 CLAUDE.md	15-50 行	80
主题规则文件	20-80 行	120

内容应放在哪里

根目录 CLAUDE.md

• 项目名称、用途、所有者
• 技术栈摘要
• 构建/部署/测试命令（可直接复制粘贴）
• 目录结构概览
• 关键的“绝不执行 X”规则
• 关键集成及机密信息的位置

子目录 CLAUDE.md

• 该组件的外部服务集成
• 此区域特有且不明显的配置
• 目录专用命令
• 在此目录中工作时需要注意的问题

不创建的情况：父级已涵盖、目录内容一目了然，或内容不足 10 行。

.claude/rules/ 主题文件

• 弥补训练数据截止时间差异的修正规则（例如 API 变更、已弃用模式）
• 编码模式和标准
• 特定平台的格式规则
• 防错模式

docs/ 和 ARCHITECTURE.md

• 详细的系统架构（组件图、数据流）
• 数据库架构和迁移指南
• API 端点目录
• Claude 应按需阅读、而非每次会话都阅读的内容

经验法则：每次会话都需要的内容放在 CLAUDE.md 中。偶尔查阅的参考资料放在 docs/ 中。

要删除的内容

• Claude 在训练中已经了解的内容
• 对标准框架的冗长说明
• 变更日志或版本历史（使用 git）
• 重复内容（CLAUDE.md 与 docs/、ARCHITECTURE.md 或 README.md 之间）
• 从未完成的“TODO”事项
• 与项目无关的通用建议

项目类型检测

审计脚本通过文件是否存在来检测项目类型，并建议相应的文档：

指示项	类型	建议的文档
wrangler.jsonc / wrangler.toml	Cloudflare Worker	ARCHITECTURE.md
vite.config.* + .tsx 文件	Vite/React	ARCHITECTURE.md
next.config.*	Next.js	ARCHITECTURE.md
src/index.ts 中的 MCP 模式	MCP 服务	ARCHITECTURE.md、API_ENDPOINTS.md
src/routes/ 或 src/api/	API 项目	API_ENDPOINTS.md、DATABASE_SCHEMA.md
Drizzle/Prisma 配置	数据库	DATABASE_SCHEMA.md

所有项目都需要 CLAUDE.md。仅在项目类型需要时添加其他文档。完整的检测启发式规则和文档模板，请参阅 references/project-types.md。

自主性规则

• 直接执行：运行审计、检测项目类型、找出缺失项并起草修改
• 简短确认：应用修改（一次性确认是/否，而非逐项确认）
• 先询问：删除现有内容、大幅重组（移动 50 行以上）、在内容存在歧义时从零创建项目文档

质量评分

审计脚本根据 6 项标准为每个 CLAUDE.md 评分（满分 100 分）：

标准	分值	衡量内容
命令/工作流	20	是否记录构建、测试和部署
架构清晰度	20	结构、关系、入口点
不明显的模式	15	注意事项、特殊之处、警告
简洁性	15	内容精炼、无冗余
时效性	15	引用有效、命令可用
可操作性	15	可直接复制粘贴、路径真实

完整评分标准请参阅 references/quality-criteria.md。

参考文件

何时	阅读
为 CLAUDE.md 质量评分	references/quality-criteria.md
检测项目类型和预期文档	references/project-types.md
创建新的 CLAUDE.md 或规则文件	references/templates.md
设置提交时自动捕获	references/commit-hook.md

脚本

• scripts/audit_memory.py — 扫描全部四层、评估质量、检测项目类型，并报告占用和重叠情况
  • python3 audit_memory.py [repo-path] — 输出人类可读的报告
  • python3 audit_memory.py [repo-path] --json — 输出结构化 JSON