Back to Details

context-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Context Manager

上下文管理器

Manage the Claude Code memory hierarchy and audit the full markdown landscape of a project. Produces well-organised memory files, detects documentation overlap, and reports the total context footprint.
管理Claude Code记忆层级并审计项目的完整Markdown体系。生成组织有序的记忆文件，检测文档重叠情况，并报告总上下文占用量。

Four Context Layers

四个上下文层级

LayerLocationPurposeWhat this skill does
Memory
./CLAUDE.md
, subdirs, 
.claude/rules/*.md
Project context, commands, architecture, rulesAudit, score, maintain
Project docs
ARCHITECTURE.md
, 
DATABASE_SCHEMA.md
, 
API_ENDPOINTS.md
, 
docs/**/*.md
Technical documentationCheck existence per project type, flag staleness, detect CLAUDE.md overlap
Session
SESSION.md
, 
PROJECT_BRIEF.md
Temporary progress trackingReport presence + size (managed by dev-session)
Public
README.md
, 
CONTRIBUTING.md
, other root 
.md
Public-facing docsDetect CLAUDE.md duplication
Auto-memory (
~/.claude/projects/*/memory/MEMORY.md
) is also scanned for awareness but managed by Claude automatically.
层级位置用途该技能的作用
记忆层
./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自动管理。

Operating Modes

操作模式

Mode 1: Session Capture

模式1：会话捕获

When: End of session, "capture learnings", "update CLAUDE.md with what we learned"
  1. Review the conversation for discoveries worth preserving:
    • Commands that worked (or didn't)
    • Gotchas and workarounds found
    • Architecture decisions made
    • Configuration quirks discovered
    • Patterns that would help future sessions
  2. Categorise each discovery using the placement decision tree below
  3. Draft all changes as diffs in a single batch
  4. Present the batch — apply after a single yes/no confirmation
Keep it concise: one line per concept. No verbose explanations, no generic advice.
触发场景：会话结束时、输入"capture learnings"、"update CLAUDE.md with what we learned"
  1. 回顾对话内容，筛选值得保留的发现：
    • 可行（或不可行）的命令
    • 发现的陷阱与解决方法
    • 做出的架构决策
    • 发现的配置异常
    • 对未来会话有帮助的模式
  2. 使用下方的放置决策树对每个发现进行分类
  3. 将所有更改以差异形式批量草拟
  4. 展示批量更改内容，在单次确认（是/否）后应用
注意简洁：每个概念仅用一行描述。无需冗长解释，无需通用建议。

Mode 2: Full Audit

模式2：全面审计

When: "audit context", "audit memory", "check project docs", periodic maintenance, working in a neglected project
  1. Run the audit script:
    bash
    python3 skills/context-manager/scripts/audit_memory.py [repo-path]
  2. Review the output:
    • Memory layer: CLAUDE.md sizes, quality scores, rules file sizes
    • Project docs: existence, staleness, overlap with CLAUDE.md
    • Session/public: presence and size
    • Markdown footprint: total KB by layer
    • Overlap warnings: sections duplicated between files
  3. Generate changes autonomously — create, update, or flag files as needed
  4. Present all changes as a single batch for approval
  5. Apply approved changes
For large repos, delegate to a sub-agent:
Task(subagent_type: "general-purpose",
  prompt: "Run python3 skills/context-manager/scripts/audit_memory.py /path/to/repo
           and summarise the findings.")
触发场景：输入"audit context"、"audit memory"、"check project docs"、定期维护、处理被忽视的项目
  1. 运行审计脚本：
    bash
    python3 skills/context-manager/scripts/audit_memory.py [repo-path]
  2. 查看输出内容：
    • 记忆层：CLAUDE.md文件大小、质量评分、规则文件大小
    • 项目文档层：存在性、过期情况、与CLAUDE.md的重叠情况
    • 会话/公共层：存在性及大小
    • Markdown占用量：各层级的总KB数
    • 重叠警告：文件间重复的章节
  3. 自主生成更改内容——根据需要创建、更新或标记文件
  4. 将所有更改作为单个批次呈现以获取批准
  5. 应用已批准的更改
对于大型仓库，可委托给子代理：
Task(subagent_type: "general-purpose",
  prompt: "Run python3 skills/context-manager/scripts/audit_memory.py /path/to/repo
           and summarise the findings.")

Mode 3: Restructure

模式3：重构

When: "restructure memory", root CLAUDE.md over 200 lines, first-time memory setup
  1. Run full audit (Mode 2) first
  2. Split oversized files:
    • Extract topic sections from root CLAUDE.md into 
      .claude/rules/<topic>.md
    • Extract directory-specific content into sub-directory CLAUDE.md files
    • Move detailed technical content from CLAUDE.md to 
      docs/
      or 
      ARCHITECTURE.md
      if it's reference material, not operational context
  3. Resolve overlaps: if CLAUDE.md duplicates ARCHITECTURE.md or docs/, remove the duplication
  4. Create missing documentation files based on project type
  5. Present the restructure plan, apply after approval
触发场景：输入"restructure memory"、根目录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. 展示重构计划，在批准后应用

Placement Decision Tree

放置决策树

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/rules/<topic>.md
│         （修正规则、API模式、编码标准）
└── 否 → 是否特定于某个子目录？
    ├── 是 → <dir>/CLAUDE.md
│         （集成、特定目录的陷阱）
    └── 否 → 是参考文档还是操作上下文？
        ├── 参考文档 → ARCHITECTURE.md 或 docs/
        │               （系统设计、架构、详细流程）
        └── 操作上下文 → ./CLAUDE.md（项目根目录）
                          （项目标识、技术栈、命令、关键规则）

Size Targets

大小目标

File TypeTargetMaximum
Root CLAUDE.md50-150 lines200
Sub-directory CLAUDE.md15-50 lines80
Rules topic file20-80 lines120
文件类型目标范围最大值
根目录CLAUDE.md50-150行200行
子目录CLAUDE.md15-50行80行
规则主题文件20-80行120行

What Belongs Where

内容归属指南

Root CLAUDE.md

根目录CLAUDE.md

  • Project name, purpose, owner
  • Tech stack summary
  • Build/deploy/test commands (copy-paste ready)
  • Directory structure overview
  • Critical "never do X" rules
  • Key integrations and secrets locations
  • 项目名称、用途、所有者
  • 技术栈摘要
  • 构建/部署/测试命令（可直接复制粘贴）
  • 目录结构概述
  • 关键的"禁止操作X"规则
  • 核心集成及密钥位置

Sub-directory CLAUDE.md

子目录CLAUDE.md

  • External service integrations for that component
  • Non-obvious configuration specific to this area
  • Directory-specific commands
  • Gotchas when working in this directory
Don't create when: parent covers it, directory is self-explanatory, content would be under 10 lines.
  • 该组件的外部服务集成
  • 该区域特有的非显而易见配置
  • 特定目录的命令
  • 在该目录工作时的注意事项
无需创建的情况：父目录已涵盖相关内容、目录本身易于理解、内容不足10行。

.claude/rules/ topic files

.claude/rules/ 主题文件

  • Correction rules bridging training cutoff (e.g. API changes, deprecated patterns)
  • Coding patterns and standards
  • Platform-specific formatting rules
  • Error prevention patterns
  • 弥补训练截止日期后的修正规则（如API变更、已弃用模式）
  • 编码模式与标准
  • 平台特定的格式规则
  • 错误预防模式

docs/ and ARCHITECTURE.md

docs/ 和 ARCHITECTURE.md

  • Detailed system architecture (component diagrams, data flows)
  • Database schemas and migration guides
  • API endpoint catalogues
  • Content that Claude should read on demand, not every session
Rule of thumb: If it's needed every session, put it in CLAUDE.md. If it's reference material consulted occasionally, put it in docs/.
  • 详细的系统架构（组件图、数据流）
  • 数据库架构与迁移指南
  • API端点目录
  • Claude按需查阅而非每次会话都需要的内容
经验法则：如果每次会话都需要，放在CLAUDE.md中。如果是偶尔查阅的参考资料，放在docs/中。

What to delete

应删除的内容

  • Content Claude already knows from training
  • Verbose explanations of standard frameworks
  • Changelogs or version history (use git)
  • Duplicated content (between CLAUDE.md and docs/, ARCHITECTURE.md, or README.md)
  • "TODO" items that were never completed
  • Generic advice not specific to the project
  • Claude从训练中已掌握的内容
  • 对标准框架的冗长解释
  • 变更日志或版本历史（使用git管理）
  • 重复内容（CLAUDE.md与docs/、ARCHITECTURE.md或README.md之间）
  • 从未完成的"TODO"项
  • 非项目特定的通用建议

Project Type Detection

项目类型检测

The audit script detects project type from file presence and suggests appropriate documentation:
IndicatorTypeSuggested Docs
wrangler.jsonc
/ 
wrangler.toml
Cloudflare WorkerARCHITECTURE.md
vite.config.*
+ 
.tsx
files		Vite/ReactARCHITECTURE.md
next.config.*
Next.jsARCHITECTURE.md
MCP patterns in 
src/index.ts
MCP ServerARCHITECTURE.md, API_ENDPOINTS.md
src/routes/
or 
src/api/
API ProjectAPI_ENDPOINTS.md, DATABASE_SCHEMA.md
Drizzle/Prisma configDatabaseDATABASE_SCHEMA.md
All projects get CLAUDE.md. Additional docs only when the project type warrants them. See references/project-types.md for full detection heuristics and doc templates.
审计脚本通过文件存在情况检测项目类型，并建议相应的文档：
标识类型建议文档
wrangler.jsonc
/ 
wrangler.toml
Cloudflare WorkerARCHITECTURE.md
vite.config.*
+ 
.tsx
文件		Vite/ReactARCHITECTURE.md
next.config.*
Next.jsARCHITECTURE.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。

Autonomy Rules

自主操作规则

  • Just do it: Run audit, detect project type, identify gaps, draft changes
  • Brief confirmation: Apply changes (single batch yes/no, not item-by-item)
  • Ask first: Delete existing content, major restructures (moving 50+ lines), create new project docs from scratch where there's ambiguity about content
  • 直接执行：运行审计、检测项目类型、识别缺口、草拟更改
  • 简短确认：应用更改（单次批量确认是/否，而非逐项确认）
  • 先询问：删除现有内容、重大重构（移动50行以上内容）、在内容存在歧义时从头创建新的项目文档

Quality Scoring

质量评分

The audit script scores each CLAUDE.md on 6 criteria (100 points):
CriterionPointsWhat it measures
Commands/Workflows20Build, test, deploy documented
Architecture Clarity20Structure, relationships, entry points
Non-Obvious Patterns15Gotchas, quirks, warnings
Conciseness15Dense content, no filler
Currency15References valid, commands work
Actionability15Copy-paste ready, real paths
See references/quality-criteria.md for the full rubric.
审计脚本从6个维度对每个CLAUDE.md进行评分（满分100分）：
维度分值衡量内容
命令/工作流20构建、测试、部署命令是否已记录
架构清晰度20结构、关系、入口点是否清晰
非显而易见模式15是否记录陷阱、异常、警告
简洁性15内容是否精炼、无冗余
时效性15参考内容是否有效、命令是否可行
可操作性15是否可直接复制粘贴、路径是否真实有效
完整评分标准请参阅references/quality-criteria.md。

Reference Files

参考文件

WhenRead
Scoring CLAUDE.md qualityreferences/quality-criteria.md
Detecting project type and expected docsreferences/project-types.md
Creating new CLAUDE.md or rules filesreferences/templates.md
场景查阅文件
为CLAUDE.md质量评分references/quality-criteria.md
检测项目类型及所需文档references/project-types.md
创建新的CLAUDE.md或规则文件references/templates.md

Scripts

脚本

  • scripts/audit_memory.py
    — Scan all four layers, score quality, detect project type, report footprint and overlap 
    • python3 audit_memory.py [repo-path]
      — human-readable report
    • python3 audit_memory.py [repo-path] --json
      — structured JSON output
  • scripts/audit_memory.py
    — 扫描四个层级、为质量评分、检测项目类型、报告占用量与重叠情况 
    • python3 audit_memory.py [repo-path]
      — 生成人类可读的报告
    • python3 audit_memory.py [repo-path] --json
      — 生成结构化JSON输出