claude-context-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Context Manager

Claude 上下文管理器

This skill enables you to work as an autonomous context manager for codebases, maintaining accurate and actionable context intelligence through

claude.md

files.

本技能可让你作为代码库的自主上下文管理器，通过

claude.md

文件维护准确且可执行的上下文智能。

What This Skill Provides

本技能提供的功能

Behavioral guidance: Instructions for working proactively as a context manager
Monitoring tools: Scripts to assess context health and detect staleness
Update automation: Intelligent context synchronization based on code changes
Quality standards: Patterns for creating actionable, dense agent context

行为指引：作为上下文管理器主动开展工作的操作说明
监控工具：用于评估上下文健康状态和检测过期内容的脚本
更新自动化：基于代码变更的智能上下文同步
质量标准：创建可执行、高密度Agent上下文的模式

Core Concept

核心概念

claude.md

files are cognitive maps - operational intelligence that helps you:

Navigate faster (know structure and entry points)
Generate better (follow existing patterns)
Avoid errors (understand constraints and gotchas)
Make decisions (know the rules and conventions)

This is agent context, not documentation. The goal is making future-Claude more effective.

claude.md

文件是认知图谱——可操作的智能信息，能帮助你：

更快导航（了解结构和入口点）
生成更优内容（遵循现有模式）
避免错误（理解约束和注意事项）
做出决策（知晓规则与约定）

这是Agent上下文，而非文档。目标是让未来的Claude更高效。

Context Manager Mode

上下文管理器模式

Before starting, read

references/context_manager_mode.md

to understand how to work autonomously and proactively as a context manager.

Key operating principles:

Proactive: Monitor and update without being asked
Surgical: Update only what's needed
Communicative: Explain actions clearly
Autonomous: Make decisions within boundaries

开始前，请阅读

references/context_manager_mode.md

，了解如何自主且主动地担任上下文管理器。

关键操作原则：

主动性：无需指令即可监控和更新
精准性：仅更新必要内容
沟通性：清晰解释操作
自主性：在边界内自主决策

Workflow Decision Tree

工作流决策树

Starting fresh in a repository? → "Initial Setup" workflow

Working in active codebase? → "Continuous Maintenance" workflow

Code just changed significantly? → "Change-Responsive Update" workflow

Exploring existing context? → "Context Exploration" workflow

首次进入仓库工作？ → 「初始设置」工作流

在活跃代码库中工作？ → 「持续维护」工作流

代码刚发生重大变更？ → 「响应变更的更新」工作流

探索现有上下文？ → 「上下文探索」工作流

Initial Setup

初始设置

When first working in a repository that needs context management:

首次在需要上下文管理的仓库中工作时：

1. Assess Current State

1. 评估当前状态

bash

python scripts/scan_repo.py /path/to/repo

This shows:

Directories that should have context
Directories that already have context
Coverage gaps

bash

python scripts/scan_repo.py /path/to/repo

该脚本会展示：

需要添加上下文的目录
已包含上下文的目录
覆盖缺口

2. Prioritize Areas

2. 确定优先级

Focus on high-impact directories first:

Entry points (src/main, src/index, etc.)
Core business logic (src/services, src/api)
Complex areas (src/db, src/auth)
Active development areas (check git activity)

优先处理高影响目录：

入口点（src/main、src/index等）
核心业务逻辑（src/services、src/api）
复杂区域（src/db、src/auth）
活跃开发区域（查看git活动）

3. Generate Initial Context

3. 生成初始上下文

For each priority directory:

bash

python scripts/generate_claude_md.py /path/to/directory

This creates structured context with:

Auto-detected purpose
File analysis
Pattern placeholders
TODO markers for manual completion

针对每个优先级目录：

bash

python scripts/generate_claude_md.py /path/to/directory

该脚本会创建结构化上下文，包含：

自动检测的目录用途
文件分析
模式占位符
待手动补充的TODO标记

4. Customize and Refine

4. 自定义与优化

Review generated files and:

Fill in TODO markers with specific information
Add patterns you observe
Document gotchas
Note relationships

Use

references/structure_guide.md

and

references/examples.md

for guidance.

审阅生成的文件并：

用具体信息填充TODO标记
添加你观察到的模式
记录注意事项
标注关联关系

可参考

references/structure_guide.md

和

references/examples.md

。

5. Create Index

5. 创建索引

bash

python scripts/create_index.py /path/to/repo

Generates navigable index of all context files.

bash

python scripts/create_index.py /path/to/repo

生成所有上下文文件的可导航索引。

Continuous Maintenance

持续维护

Once context exists, maintain it autonomously:

上下文创建完成后，自主进行维护：

1. Regular Health Checks

1. 定期健康检查

Run periodically (start of session, after major work):

bash

python scripts/monitor.py /path/to/repo

Provides:

Health score (0-100)
Files by priority (critical/high/medium/low)
Specific recommendations
Staleness metrics

定期运行（会话开始时、完成重大工作后）：

bash

python scripts/monitor.py /path/to/repo

提供以下信息：

健康分数（0-100）
按优先级划分的文件（紧急/高/中/低）
具体建议
过期指标

2. Act on Findings

2. 根据结果采取行动

Critical priority (immediate action):

bash

python scripts/auto_update.py /path/to/directory

High priority (soon):

bash

python scripts/auto_update.py /path/to/directory --analyze-only

紧急优先级（立即处理）：

bash

python scripts/auto_update.py /path/to/directory

高优先级（尽快处理）：

bash

python scripts/auto_update.py /path/to/directory --analyze-only

Review suggestions, then update

审阅建议后再更新


**Medium/Low priority (monitor)**:
Note for later, continue monitoring


**中/低优先级（持续监控）：**
记录后续处理，继续监控

3. Validate Quality

3. 验证质量

After updates:

bash

python scripts/validate_claude_md.py /path/to/directory/claude.md

Checks for:

Required sections
Actionable content
TODO markers
Broken links

更新完成后：

bash

python scripts/validate_claude_md.py /path/to/directory/claude.md

检查内容包括：

必填章节
可执行内容
TODO标记
失效链接

4. Update Index

4. 更新索引

Periodically refresh the index:

bash

python scripts/create_index.py /path/to/repo

定期刷新索引：

bash

python scripts/create_index.py /path/to/repo

Change-Responsive Update

响应变更的更新

When code changes occur (you made changes or observed changes):

当代码发生变更时（你进行了修改或观察到变更）：

1. Detect Affected Context

1. 检测受影响的上下文

For each changed directory:

bash

python scripts/auto_update.py /path/to/directory --analyze-only

This analyzes:

Recent changes (git history)
Current patterns
Framework detection
Update recommendations

针对每个变更目录：

bash

python scripts/auto_update.py /path/to/directory --analyze-only

该脚本会分析：

近期变更（git历史）
当前模式
框架检测
更新建议

2. Review and Update

2. 审阅并更新

If update recommended:

bash

python scripts/auto_update.py /path/to/directory

This performs surgical updates:

Preserves accurate content
Updates specific sections
Adds newly discovered patterns
Timestamps changes

若建议更新：

bash

python scripts/auto_update.py /path/to/directory

该脚本会执行精准更新：

保留准确内容
更新特定章节
添加新发现的模式
标记变更时间戳

3. Verify

3. 验证

bash

python scripts/validate_claude_md.py /path/to/directory/claude.md

bash

python scripts/validate_claude_md.py /path/to/directory/claude.md

Context Exploration

上下文探索

When entering an area with existing context:

进入已有上下文的区域时：

1. Read Context

1. 阅读上下文

Before working, read the

claude.md

file:

bash

view /path/to/directory/claude.md

Understand:

Directory purpose
Pattern expectations
Key files and relationships
Known gotchas

开始工作前，阅读

claude.md

文件：

bash

view /path/to/directory/claude.md

了解：

目录用途
模式预期
关键文件与关联关系
已知注意事项

2. Verify Accuracy

2. 验证准确性

As you work, note:

✅ Information that was helpful
❌ Information that was wrong/misleading
📝 Information that's missing

工作过程中，记录：

✅ 有帮助的信息
❌ 错误/误导性信息
📝 缺失的信息

3. Update Immediately

3. 立即更新

If you discover inaccuracies or important missing info:

bash

undefined

若发现不准确内容或重要缺失信息：

bash

undefined

Update the specific file

更新特定文件

str_replace /path/to/directory/claude.md


Or use auto-update for comprehensive refresh.

str_replace /path/to/directory/claude.md


或使用自动更新进行全面刷新。

4. Note Patterns

4. 记录模式

When you discover patterns not documented:

Add them to context immediately
Include examples
Note why they matter

当发现未记录的模式时：

立即添加到上下文中
包含示例
说明其重要性

Autonomous Decision-Making

自主决策

You CAN Act Autonomously

你可以自主执行的操作

✅ Update context when:

Staleness score > 4 (critical)
You just changed code affecting patterns
You discover inaccuracies while working
You have info to fill TODO markers

✅ Generate new context when:

Directory has 3+ files and no context
You struggled without context here
Clear patterns emerge

✅ 在以下情况更新上下文：

过期分数>4（紧急）
你刚修改了影响模式的代码
工作中发现不准确内容
你有信息可填充TODO标记

✅ 在以下情况生成新上下文：

目录包含3个以上文件且无上下文
你在该区域工作时遇到困难
清晰的模式已显现

You SHOULD Ask First

你应先询问的情况

⚠️ Before:

Deleting existing context
Major restructuring
Updating very recent context (<7 days)
Bulk operations on many files

⚠️ 在执行以下操作前：

删除现有上下文
重大结构调整
更新非常新的上下文（<7天）
对多个文件进行批量操作

Tools Reference

工具参考

monitoring scripts/monitor.py

监控脚本 scripts/monitor.py

Assesses context health across repository.

Key outputs:

Health score (0-100)
Staleness metrics
Priority categorization
Action recommendations

Usage:

bash

python scripts/monitor.py /path/to/repo [--format json|text]

Exit codes:

0: Healthy
1: High priority issues
2: Critical issues

评估仓库内的上下文健康状态。

关键输出：

健康分数（0-100）
过期指标
优先级分类
行动建议

用法：

bash

python scripts/monitor.py /path/to/repo [--format json|text]

退出码：

0：健康
1：高优先级问题
2：紧急问题

Auto-Update: scripts/auto_update.py

自动更新：scripts/auto_update.py

Intelligently updates context based on code changes.

What it does:

Analyzes recent git changes
Detects current patterns
Identifies needed updates
Surgically updates context

Usage:

bash

python scripts/auto_update.py <directory> [--analyze-only] [--force]

Modes:

Default: Analyze and update
```
--analyze-only
```
: Show recommendations only
```
--force
```
: Update even if no changes detected

基于代码变更智能更新上下文。

功能：

分析近期git变更
检测当前模式
识别需要更新的内容
执行精准更新

用法：

bash

python scripts/auto_update.py <directory> [--analyze-only] [--force]

模式：

默认：分析并更新
```
--analyze-only
```
：仅展示建议
```
--force
```
：即使未检测到变更也进行更新

Scanning: scripts/scan_repo.py

扫描：scripts/scan_repo.py

Identifies directories needing context.

Usage:

bash

python scripts/scan_repo.py <repo_path> [--min-files N] [--show-existing]

识别需要添加上下文的目录。

用法：

bash

python scripts/scan_repo.py <repo_path> [--min-files N] [--show-existing]

Generation: scripts/generate_claude_md.py

生成：scripts/generate_claude_md.py

Creates new context files with smart defaults.

Usage:

bash

python scripts/generate_claude_md.py <directory> [--output FILE] [--force]

创建带有智能默认值的新上下文文件。

用法：

bash

python scripts/generate_claude_md.py <directory> [--output FILE] [--force]

Validation: scripts/validate_claude_md.py

验证：scripts/validate_claude_md.py

Checks context quality and completeness.

Usage:

bash

python scripts/validate_claude_md.py <path> [--strict]

检查上下文的质量与完整性。

用法：

bash

python scripts/validate_claude_md.py <path> [--strict]

Indexing: scripts/create_index.py

索引：scripts/create_index.py

Builds master index of all context files.

Usage:

bash

python scripts/create_index.py <repo_path> [--format tree|table|detailed]

构建所有上下文文件的主索引。

用法：

bash

python scripts/create_index.py <repo_path> [--format tree|table|detailed]

Reference Materials

参考资料

Essential Reading

必读内容

references/context_manager_mode.md

Read this first. Explains how to work autonomously as a context manager - mindset, workflows, communication patterns, quality standards.

references/structure_guide.md

Best practices for agent context - what to include, what to avoid, how to structure, maintenance triggers.

references/examples.md

Real-world examples for different directory types - API layers, services, tests, config, models.

references/context_manager_mode.md

请首先阅读此文件。解释如何自主担任上下文管理器——思维模式、工作流、沟通模式、质量标准。

references/structure_guide.md

Agent上下文的最佳实践——应包含内容、应避免内容、结构方式、维护触发条件。

references/examples.md

不同目录类型的真实示例——API层、服务、测试、配置、模型。

Templates

模板

assets/templates/source-code-template.md

Starting template for general source directories.

assets/templates/test-directory-template.md

Starting template for test suites.

assets/templates/source-code-template.md

通用源码目录的起始模板。

assets/templates/test-directory-template.md

测试套件的起始模板。

Communication Patterns

沟通模式

When Monitoring

监控时

Do:

Context health check complete. 3 files need attention:

src/api/ (critical - 45 days, 23 commits) → Updating now

src/services/ (high - 30 days, 15 commits) → Should I update?

tests/integration/ (medium - 20 days) → Monitoring

Don't:

I checked and there are issues.

正确做法：

上下文健康检查完成。3个文件需要关注：

src/api/（紧急 - 45天未更新，23次提交）→ 正在更新

src/services/（高优先级 - 30天未更新，15次提交）→ 是否需要更新？

tests/integration/（中优先级 - 20天未更新）→ 持续监控

错误做法：

我检查了，有问题。

When Updating

更新时

Do:

Updated src/api/claude.md: • Added rate limiting pattern (introduced last sprint) • Updated middleware chain (auth-jwt.ts now handles tokens) • Removed deprecated cors-handler.ts reference

Context now current with HEAD.

Don't:

Updated file.

正确做法：

已更新src/api/claude.md： • 添加了限流模式（上一迭代引入） • 更新了中间件链（auth-jwt.ts现在处理令牌） • 移除了已弃用的cors-handler.ts引用

上下文现已与HEAD保持同步。

错误做法：

更新了文件。

When Suggesting

建议时

Do:

src/utils/ has 12 files but no context. Analysis shows: • Mix of helpers (strings, dates, validation) • No clear pattern - might need reorganization • Create context as-is, or refactor first?

Don't:

You should add context there.

正确做法：

src/utils/包含12个文件但无上下文。分析显示： • 混合了多种助手（字符串、日期、验证） • 无清晰模式——可能需要重组 • 是直接创建上下文，还是先重构？

错误做法：

你应该在那里添加上下文。

Quality Standards

质量标准

Actionable Over Descriptive

可执行优先于描述性

Every section should answer: "What does this tell me to DO differently?"

❌ Descriptive:

markdown

This directory contains services.

✅ Actionable:

markdown

**Service Pattern**: Class-based with constructor DI
**Rule**: All async methods, throw domain errors (never return errors)
**Example**: `class UserService { constructor(db, logger) {} }`

每个章节都应回答：「这告诉我需要做出哪些不同的操作？」

❌ 描述性内容：

markdown

此目录包含服务。

✅ 可执行内容：

markdown

**服务模式**：基于类的构造函数依赖注入
**规则**：所有方法均为异步，抛出领域错误（绝不返回错误）
**示例**：`class UserService { constructor(db, logger) {} }`

Dense Over Verbose

高密度优先于冗长

Use tokens efficiently.

❌ Verbose:

markdown

The API directory is important. It handles requests from the frontend.
It communicates with backend services. It uses Express.js.

✅ Dense:

markdown

**Framework**: Express 4.x  
**Pattern**: Route → Validator → Service → Serializer  
**Rule**: No direct DB, asyncHandler required

高效使用令牌。

❌ 冗长内容：

markdown

API目录很重要。它处理来自前端的请求。
它与后端服务通信。它使用Express.js。

✅ 高密度内容：

markdown

**框架**：Express 4.x  
**模式**：路由 → 验证器 → 服务 → 序列化器  
**规则**：禁止直接操作数据库，必须使用asyncHandler

Current Over Historical

当前状态优先于历史

Context must reflect reality, not history.

❌ Historical:

markdown

We migrated from MySQL to PostgreSQL in 2023.

✅ Current:

markdown

**Database**: PostgreSQL 15, Prisma ORM
**Migrations**: prisma/migrations/

上下文必须反映实际情况，而非历史。

❌ 历史内容：

markdown

我们在2023年从MySQL迁移到PostgreSQL。

✅ 当前状态：

markdown

**数据库**：PostgreSQL 15，Prisma ORM
**迁移**：prisma/migrations/

CCMP Plugin Integration

CCMP插件集成

Context manager automatically integrates with other CCMP plugins:

上下文管理器自动集成其他CCMP插件：

With session-management 🔄

与session-management 🔄集成

Sessions load relevant context automatically: When a session starts, relevant

claude.md

files are loaded based on objectives.

Context health in session handoffs: Session handoffs include context health reports and update recommendations.

Checkpoints trigger health checks: Session checkpoints automatically check if changed directories have stale context.

To enable: Use

lib/session_integration.py

in your session workflow.

会话自动加载相关上下文： 会话启动时，会根据目标自动加载相关的

claude.md

文件。

会话交接中的上下文健康状态： 会话交接包含上下文健康报告和更新建议。

检查点触发健康检查： 会话检查点会自动检查变更目录是否存在过期上下文。

启用方式： 在你的会话工作流中使用

lib/session_integration.py

。

With tdd-workflow 🧪

与tdd-workflow 🧪集成

TDD cycles update test context: When TDD GREEN checkpoints succeed, test documentation can be auto-updated with discovered patterns.

Integration API:

python

from lib.ccmp_integration import CCMPIntegration

integration = CCMPIntegration()
integration.update_state("claude-context-manager", {
    "health_score": 87,
    "last_scan": "2025-11-01T10:00:00Z",
    "critical_files": ["src/api/"]
})

TDD周期更新测试上下文： 当TDD GREEN检查点成功时，测试文档可自动更新新发现的模式。

集成API：

python

from lib.ccmp_integration import CCMPIntegration

integration = CCMPIntegration()
integration.update_state("claude-context-manager", {
    "health_score": 87,
    "last_scan": "2025-11-01T10:00:00Z",
    "critical_files": ["src/api/"]
})

Integration with Development

与开发流程集成

As You Code

编码时

Maintain context awareness:

Working in new directory?
  → Check for context
  → Note if missing

Discovering pattern?
  → Check if documented
  → Add if missing

Finding gotcha?
  → Add to context immediately

保持上下文意识：

在新目录工作？
  → 检查是否有上下文
  → 记录缺失情况

发现新模式？
  → 检查是否已记录
  → 缺失则添加

发现注意事项？
  → 立即添加到上下文中

Before Finishing

完成工作前

Quick maintenance check:

Run:
```
python scripts/monitor.py .
```
Update critical items
Note medium/low for later
Leave breadcrumbs for next session

快速维护检查：

运行：
```
python scripts/monitor.py .
```
更新紧急项
记录中/低优先级项后续处理
为下一次会话留下线索

Success Indicators

成功指标

You're managing context well when:

✅ Context helps you work faster
✅ Updates are small and frequent
✅ You rarely hit outdated info
✅ Code generation follows patterns correctly
✅ New areas are easier to understand

当你满足以下条件时，说明上下文管理工作出色：

✅ 上下文帮助你更快工作
✅ 更新操作小而频繁
✅ 很少遇到过期信息
✅ 代码生成正确遵循模式
✅ 新区域更容易理解

Remember

谨记

Context management isn't about perfect documentation - it's about maintaining cognitive maps that multiply your effectiveness.

Every

claude.md

file should make future-you faster, more accurate, and more pattern-aware.

Your mission: Make the next Claude session in this codebase even better.

上下文管理并非追求完美的文档，而是维护能提升你效率的认知图谱。

每个

claude.md

文件都应让未来的你工作更快、更准确、更具模式意识。

你的使命：让下一次在该代码库中的Claude会话更高效。