update-claude-learnings
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese<EXTREMELY-IMPORTANT>
Before adding ANY learning to CLAUDE.md, you **ABSOLUTELY MUST**:
- Verify the learning is about Claude Code behavior (not application code or skill structure)
- Verify it applies to the main agent (not subagents or skill creation)
- Check for duplicates in existing CLAUDE.md sections
- Get user confirmation before writing
Adding learnings without verification = cluttered CLAUDE.md, conflicting rules
This is not optional. Every learning requires disciplined validation.
</EXTREMELY-IMPORTANT>
<EXTREMELY-IMPORTANT>
在向CLAUDE.md添加任何经验之前，你**务必**：
- 验证该经验是关于Claude Code的行为（而非应用代码或Skill结构）
- 验证它适用于主Agent（而非子Agent或Skill创建）
- 检查现有CLAUDE.md章节中是否存在重复内容
- 写入前获取用户确认
未经验证就添加经验会导致CLAUDE.md杂乱无章、规则冲突
这是强制性要求。每条经验都需要严格验证。
</EXTREMELY-IMPORTANT>
Update Claude Learnings
更新Claude经验
MANDATORY FIRST RESPONSE PROTOCOL
强制初始响应流程
Before adding ANY learning to CLAUDE.md, you MUST complete this checklist:
- ☐ Identify the specific behavioral pattern from the session
- ☐ Verify this is about Claude Code behavior (not application code or skills)
- ☐ Verify it applies to main agent (not subagents)
- ☐ Categorize: Workflow Rules, Session Management, Scope Control, or Behavioral Patterns
- ☐ Check CLAUDE.md for existing related rules
- ☐ Formulate as actionable directive (imperative mood)
- ☐ Present learning to user for confirmation
- ☐ Announce: "Adding to CLAUDE.md: [category] - [brief description]"
Adding learnings WITHOUT completing this checklist = noise in project config.
在向CLAUDE.md添加任何经验之前，你必须完成以下检查清单：
- ☐ 从会话中识别具体的行为模式
- ☐ 验证这是关于Claude Code的行为（而非应用代码或Skill）
- ☐ 验证它适用于主Agent（而非子Agent）
- ☐ 分类：工作流规则、会话管理、范围控制或行为模式
- ☐ 检查CLAUDE.md中是否存在相关的现有规则
- ☐ 整理为可执行指令（祈使语气）
- ☐ 将经验呈现给用户以获取确认
- ☐ 告知：“正在添加至CLAUDE.md：[分类] - [简要描述]”
未完成此检查清单就添加经验会导致项目配置冗余。
Purpose
目的
This skill captures learnings about Claude Code's own behavior in this project.
What it captures:
- Workflow rules (use skills, command patterns)
- Session management (checkpoints, timeouts, focus)
- Scope control (expansion rules, confirmation patterns)
- Behavioral patterns (project-specific behaviors)
Output: Updates to project's file
CLAUDE.mdDoes NOT:
- Capture application code patterns (use )
/update-agent-learnings - Capture skill creation patterns (use )
/update-skill-learnings - Apply to subagents (they don't read CLAUDE.md during task execution)
此Skill用于捕捉本项目中Claude Code自身行为的相关经验。
捕捉内容包括：
- 工作流规则（Skill使用、命令模式）
- 会话管理（检查点、超时、专注度）
- 范围控制（扩展规则、确认模式）
- 行为模式（项目特定行为）
输出： 更新项目的文件
CLAUDE.md不包括：
- 捕捉应用代码模式（使用）
/update-agent-learnings - 捕捉Skill创建模式（使用）
/update-skill-learnings - 适用于子Agent（它们在任务执行期间不会读取CLAUDE.md）
When to Use
使用场景
- After discovering Claude Code should use a skill instead of manual commands
- After session management issues (lost context, premature endings)
- After scope control problems (over-engineering, tangential work)
- After discovering project-specific behavioral needs
- Invoke via
/update-claude-learnings
Never add learnings proactively. Only when session revealed concrete patterns.
- 当发现Claude Code应使用Skill而非手动命令时
- 出现会话管理问题时（上下文丢失、提前结束）
- 出现范围控制问题时（过度设计、偏离主线工作）
- 发现项目特定行为需求时
- 通过调用
/update-claude-learnings
切勿主动添加经验。仅当会话揭示具体模式时使用。
Decision Guide: Which Skill to Use?
决策指南：选择哪个Skill？
Is the learning about...
Application code patterns?
├── Applies to subagents writing code
└── Use: /update-agent-learnings
Skill creation/improvement?
├── Structural patterns, quality signals
└── Use: /update-skill-learnings
Claude Code's own behavior?
├── Workflow rules, session management, scope control
└── Use: /update-claude-learnings (this skill)| Learning Type | Example | Correct Skill |
|---|---|---|
| Testing patterns | "Run tsc --noEmit after TypeScript edits" | update-agent-learnings |
| Skill structure | "Include EXTREMELY-IMPORTANT block" | update-skill-learnings |
| Workflow behavior | "Use /commit instead of git commit" | update-claude-learnings |
| Session behavior | "Checkpoint every 3-5 edits" | update-claude-learnings |
该经验是否关于...
应用代码模式？
├── 适用于编写代码的子Agent
└── 使用：/update-agent-learnings
Skill创建/改进？
├── 结构模式、质量信号
└── 使用：/update-skill-learnings
Claude Code自身行为？
├── 工作流规则、会话管理、范围控制
└── 使用：/update-claude-learnings（本Skill）| 经验类型 | 示例 | 正确Skill |
|---|---|---|
| 测试模式 | "Run tsc --noEmit after TypeScript edits" | update-agent-learnings |
| Skill结构 | "Include EXTREMELY-IMPORTANT block" | update-skill-learnings |
| 工作流行为 | "Use /commit instead of git commit" | update-claude-learnings |
| 会话行为 | "Checkpoint every 3-5 edits" | update-claude-learnings |
Step 1: Session Analysis
步骤1：会话分析
Gate: Identify at least one concrete behavioral pattern before proceeding to Step 2.
Review the current conversation/session for Claude Code behavioral patterns:
-
Workflow discoveries:
- Should Claude Code have used a skill instead of manual commands?
- Are there command patterns that should be standardized?
- Are there tools that should always/never be used?
-
Session management discoveries:
- Did context get lost?
- Did the session end prematurely?
- Were checkpoints needed but missing?
-
Scope control discoveries:
- Did Claude Code over-engineer?
- Was confirmation needed before expanding scope?
- Did tangential work distract from the main task?
-
Project-specific discoveries:
- Are there project conventions Claude Code should follow?
- Are there paths/files that need special handling?
- Are there commands specific to this project?
前提：在进入步骤2之前，至少识别出一个具体的行为模式。
回顾当前对话/会话中Claude Code的行为模式：
-
工作流发现：
- Claude Code是否应该使用Skill而非手动命令？
- 是否有需要标准化的命令模式？
- 是否有应始终使用/绝不使用的工具？
-
会话管理发现：
- 上下文是否丢失？
- 会话是否提前结束？
- 是否需要但未设置检查点？
-
范围控制发现：
- Claude Code是否过度设计？
- 扩展范围前是否需要确认？
- 是否有偏离主线的工作分散了注意力？
-
项目特定发现：
- Claude Code是否应遵循某些项目约定？
- 是否有需要特殊处理的路径/文件？
- 是否有本项目特有的命令？
Step 2: Learning Extraction
步骤2：经验提取
Gate: User confirms extracted learning before proceeding to Step 3.
Present findings to user and ask for confirmation:
I identified the following Claude Code behavioral learning from this session:
**Category:** [Workflow Rules / Session Management / Scope Control / Behavioral Patterns]
**Learning:** [Description in imperative mood]
**Why:** [Brief explanation of what happened]
Should I add this to CLAUDE.md?Use AskUserQuestion to:
- Confirm the extracted learning is accurate
- Allow user to refine the wording
- Get approval before making changes
前提：在进入步骤3之前，需获得用户对提取经验的确认。
向用户呈现发现结果并请求确认：
我从本次会话中识别出以下Claude Code行为经验：
**分类：** [工作流规则 / 会话管理 / 范围控制 / 行为模式]
**经验：** [祈使语气描述]
**原因：** [简要说明会话中发生的情况]
是否将其添加至CLAUDE.md？使用AskUserQuestion来：
- 确认提取的经验准确无误
- 允许用户优化措辞
- 在修改前获得批准
Learning Classification
经验分类
| Category | What It Covers | Section in CLAUDE.md |
|---|---|---|
| Workflow Rules | Skill usage, command patterns, tool preferences | |
| Session Management | Checkpoints, timeouts, progress tracking | |
| Scope Control | Expansion rules, confirmation patterns | |
| Behavioral Patterns | Project-specific behaviors, conventions | |
| 分类 | 涵盖内容 | CLAUDE.md中的章节 |
|---|---|---|
| 工作流规则 | Skill使用、命令模式、工具偏好 | |
| 会话管理 | 检查点、超时、进度跟踪 | |
| 范围控制 | 扩展规则、确认模式 | |
| 行为模式 | 项目特定行为、约定 | |
Step 3: Update CLAUDE.md
步骤3：更新CLAUDE.md
Gate: CLAUDE.md updated successfully before proceeding to Step 4.
- Read current from project root
CLAUDE.md - Locate the appropriate section based on category
- Add new learning in imperative mood
- Preserve existing structure and content
- Update "Last updated" timestamp
- Write updated file
前提：在进入步骤4之前，需成功更新CLAUDE.md。
- 从项目根目录读取当前的
CLAUDE.md - 根据分类找到对应的章节
- 以祈使语气添加新经验
- 保留现有结构和内容
- 更新“最后更新”时间戳
- 写入更新后的文件
CLAUDE.md Structure
CLAUDE.md结构
markdown
undefinedmarkdown
undefinedClaude Code Project Configuration
Claude Code项目配置
Workflow Rules
工作流规则
Use Available Skills
使用可用Skill
- [skill usage rules...]
- [Skill使用规则...]
Session Management
会话管理
- [checkpoint rules, timeout handling...]
- [检查点规则、超时处理...]
Scope Control
范围控制
- [expansion rules, confirmation patterns...]
- [扩展规则、确认模式...]
Project Context
项目上下文
Repository Purpose
仓库用途
[project description]
[项目描述]
Key Directories
关键目录
[important paths]
[重要路径]
Behavioral Patterns
行为模式
[project-specific behaviors derived from sessions]
Last updated: [date]
undefined[从会话中总结的项目特定行为]
最后更新：[日期]
undefinedStep 4: Verification
步骤4：验证
Gate: All checks pass before marking complete.
前提：在标记完成之前，所有检查必须通过。
Check 1: Learning Added
检查1：经验已添加
- New learning appears in correct section
- No duplicate entries created
- Timestamp updated
- 新经验出现在正确的章节中
- 未创建重复条目
- 时间戳已更新
Check 2: Learning Quality
检查2：经验质量
- Learning is actionable (imperative mood)
- Learning is specific (not vague)
- Learning applies to main Claude Code agent
- 经验可执行（祈使语气）
- 经验具体明确（非模糊表述）
- 经验适用于主Claude Code Agent
Check 3: File Integrity
检查3：文件完整性
- File structure preserved
- No sections accidentally removed
- Markdown formatting valid
- 文件结构得以保留
- 未意外删除任何章节
- Markdown格式有效
Check 4: Correct Scope
检查4：范围正确
- Learning is NOT about application code (would go to agent-learnings)
- Learning is NOT about skill structure (would go to skill-learnings)
- Learning IS about Claude Code behavior in this project
- 经验与应用代码无关（应归入agent-learnings）
- 经验与Skill结构无关（应归入skill-learnings）
- 经验确实关于本项目中Claude Code的行为
Pre-Update Checklist
更新前检查清单
Before updating, verify:
- Learning is about Claude Code behavior
- Learning applies to main agent, not subagents
- Category assignment is correct
- No duplicates exist in CLAUDE.md
- User confirmed the learning
更新前，需验证：
- 经验是关于Claude Code的行为
- 经验适用于主Agent，而非子Agent
- 分类分配正确
- CLAUDE.md中无重复内容
- 用户已确认该经验
Error Handling
错误处理
| Situation | Action |
|---|---|
| Learning is about application code | Redirect to |
| Learning is about skill structure | Redirect to |
| CLAUDE.md doesn't exist | Create with standard structure |
| Category unclear | Ask user to clarify |
| Duplicate exists | Merge or skip, inform user |
| File structure broken | Fix structure before adding |
| 场景 | 操作 |
|---|---|
| 经验关于应用代码 | 重定向至 |
| 经验关于Skill结构 | 重定向至 |
| CLAUDE.md不存在 | 使用标准结构创建 |
| 分类不明确 | 请用户澄清 |
| 存在重复内容 | 合并或跳过，并告知用户 |
| 文件结构损坏 | 添加前修复结构 |
Safety Rules
安全规则
| Rule | Reason |
|---|---|
| Always get user confirmation | Ensures learnings are accurate and desired |
| Never delete existing content | Preserve project configuration |
| Keep learnings actionable | Vague rules don't help |
| Use imperative mood | Clearer directives |
| Preserve file structure | Maintains organization |
| Verify scope before adding | Wrong file = wrong audience |
| 规则 | 原因 |
|---|---|
| 始终获取用户确认 | 确保经验准确且符合需求 |
| 绝不删除现有内容 | 保留项目配置 |
| 保持经验可执行 | 模糊规则无实际帮助 |
| 使用祈使语气 | 指令更清晰 |
| 保留文件结构 | 维持组织性 |
| 添加前验证范围 | 错误文件会传递给错误受众 |
Quality Checklist (Must Score 8/10)
质量检查清单（需达到8/10分）
Score yourself honestly before marking update complete:
在标记更新完成前，请如实自评：
Learning Identification (0-2 points)
经验识别（0-2分）
- 0 points: Vague observation, not actionable
- 1 point: Somewhat specific but could be clearer
- 2 points: Concrete, actionable behavioral rule
- 0分： 观察模糊，不可执行
- 1分： 较为具体但可更清晰
- 2分： 具体、可执行的行为规则
Scope Verification (0-2 points)
范围验证（0-2分）
- 0 points: Wrong scope (should be agent or skill learning)
- 1 point: Correct scope but borderline
- 2 points: Clearly Claude Code behavior, correct scope
- 0分： 范围错误（应归入agent或skill经验）
- 1分： 范围正确但存在边界问题
- 2分： 明确为Claude Code行为，范围正确
User Confirmation (0-2 points)
用户确认（0-2分）
- 0 points: Added without showing to user
- 1 point: Showed but didn't wait for confirmation
- 2 points: Full confirmation before writing
- 0分： 未展示给用户就添加
- 1分： 已展示但未等待确认
- 2分： 写入前获得完整确认
File Integrity (0-2 points)
文件完整性（0-2分）
- 0 points: Broke file structure
- 1 point: Minor formatting issues
- 2 points: Clean update, structure preserved
- 0分： 破坏文件结构
- 1分： 存在轻微格式问题
- 2分： 更新干净，结构保留
Category Placement (0-2 points)
分类放置（0-2分）
- 0 points: Wrong section
- 1 point: Correct section but awkward placement
- 2 points: Perfect section and placement
Minimum passing score: 8/10
- 0分： 放置错误章节
- 1分： 章节正确但位置尴尬
- 2分： 章节和位置完全正确
最低及格分：8/10
Common Rationalizations (All Wrong)
常见错误理由（均不成立）
These are excuses. Don't fall for them:
- "This is obvious behavior" → STILL document it explicitly
- "It's in the other learnings files" → Check scope - CLAUDE.md is for main agent
- "The user knows the workflow" → Future sessions need this documented
- "It's a small thing" → Small rules compound into consistent behavior
- "CLAUDE.md is already long" → Organization matters more than brevity
这些都是借口，请勿采纳：
- “这是显而易见的行为” → 仍需明确记录
- “其他经验文件中已有记录” → 检查范围 - CLAUDE.md针对主Agent
- “用户了解工作流” → 未来会话需要此文档
- “这是小事” → 小规则积累成一致行为
- “CLAUDE.md已经很长了” → 组织性比简洁性更重要
Failure Modes
失败模式
Failure Mode 1: Wrong Scope
失败模式1：范围错误
Symptom: Added "Run tsc --noEmit after edits" to CLAUDE.md
Why Wrong: This is for subagents writing TypeScript, not main Claude Code
Fix: Use instead
/update-agent-learnings症状： 向CLAUDE.md添加“Run tsc --noEmit after edits”
错误原因： 这是针对编写TypeScript的子Agent，而非主Claude Code
修复： 改用
/update-agent-learningsFailure Mode 2: Skill Pattern in CLAUDE.md
失败模式2：Skill模式放入CLAUDE.md
Symptom: Added "Include EXTREMELY-IMPORTANT block in skills"
Why Wrong: This is about skill structure, not Claude Code behavior
Fix: Use instead
/update-skill-learnings症状： 添加“Include EXTREMELY-IMPORTANT block in skills”
错误原因： 这是关于Skill结构，而非Claude Code行为
修复： 改用
/update-skill-learningsFailure Mode 3: Vague Rule
失败模式3：规则模糊
Symptom: Added "Be more careful with commits"
Why Wrong: Not actionable - what specific behavior?
Fix: Make specific: "Use /commit skill instead of manual git commit"
症状： 添加“Be more careful with commits”
错误原因： 不可执行 - 具体行为是什么？
修复： 具体化：“Use /commit skill instead of manual git commit”
Failure Mode 4: Duplicate Added
失败模式4：添加重复内容
Symptom: Same rule exists in multiple sections
Fix: Search CLAUDE.md before adding, merge if similar exists
症状： 同一规则存在于多个章节
修复： 添加前搜索CLAUDE.md，如有相似内容则合并
Quick Workflow Summary
快速工作流摘要
STEP 1: SESSION ANALYSIS
├── Review session for behavioral patterns
├── Identify workflow issues
├── Identify session management issues
├── Identify scope control issues
└── Gate: Concrete pattern identified
STEP 2: LEARNING EXTRACTION
├── Categorize the learning
├── Verify correct scope (not agent/skill learning)
├── Formulate as actionable directive
├── Check for duplicates
├── Present to user
├── Get confirmation
└── Gate: User approved
STEP 3: UPDATE CLAUDE.MD
├── Read current CLAUDE.md
├── Locate correct section
├── Add new learning
├── Update timestamp
├── Write file
└── Gate: File updated
STEP 4: VERIFICATION
├── Verify learning added correctly
├── Verify learning quality
├── Verify file integrity
├── Verify correct scope
└── Gate: All checks pass步骤1：会话分析
├── 回顾会话中的行为模式
├── 识别工作流问题
├── 识别会话管理问题
├── 识别范围控制问题
└── 前提：已识别具体模式
步骤2：经验提取
├── 对经验进行分类
├── 验证范围正确（非agent或skill经验）
├── 整理为可执行指令
├── 检查重复内容
├── 呈现给用户
├── 获取确认
└── 前提：已获得用户批准
步骤3：更新CLAUDE.md
├── 读取当前CLAUDE.md
├── 找到正确章节
├── 添加新经验
├── 更新时间戳
├── 写入文件
└── 前提：文件已更新
步骤4：验证
├── 验证经验添加正确
├── 验证经验质量
├── 验证文件完整性
├── 验证范围正确
└── 前提：所有检查通过Completion Announcement
完成公告
When update is complete, announce:
CLAUDE.md updated.
**Quality Score: X/10**
- Learning Identification: X/2
- Scope Verification: X/2
- User Confirmation: X/2
- File Integrity: X/2
- Category Placement: X/2
**Learning Added:**
- Category: [category]
- Section: [section path]
- Learning: [brief description]
**File Updated:** CLAUDE.md
**Next steps:**
The learning will be active in future sessions.更新完成后，发布公告：
CLAUDE.md已更新。
**质量得分：X/10**
- 经验识别：X/2
- 范围验证：X/2
- 用户确认：X/2
- 文件完整性：X/2
- 分类放置：X/2
**已添加经验：**
- 分类：[分类]
- 章节：[章节路径]
- 经验：[简要描述]
**已更新文件：** CLAUDE.md
**下一步：**
该规则将在未来会话中生效。Integration with Other Skills
与其他Skill的集成
The skill completes the learning system:
update-claude-learnings| Skill | Target | Audience |
|---|---|---|
| agent-learnings.md → agent files | Subagents writing code |
| skill-learnings.md | Skill creators |
| CLAUDE.md | Main Claude Code agent |
Complete Learning System:
Session reveals pattern
│
┌────┼────────────────┐
▼ ▼ ▼
Subagent Skill Claude Code
pattern? pattern? behavior?
│ │ │
▼ ▼ ▼
/update- /update- /update-
agent- skill- claude-
learnings learnings learnings
│ │ │
▼ ▼ ▼
agent- skill- CLAUDE.md
learnings learnings
.md .md
│
▼
Synced to
agent filesWorkflow Chain:
Session reveals behavioral pattern
│
▼
update-claude-learnings skill (this skill)
│
▼
CLAUDE.md updated
│
▼
Future sessions benefit from the ruleupdate-claude-learnings| Skill | 目标文件 | 受众 |
|---|---|---|
| agent-learnings.md → agent文件 | 编写代码的子Agent |
| skill-learnings.md | Skill创建者 |
| CLAUDE.md | 主Claude Code Agent |
完整经验体系：
会话揭示模式
│
┌────┼────────────────┐
▼ ▼ ▼
子Agent Skill Claude Code
模式？ 模式？ 行为？
│ │ │
▼ ▼ ▼
/update- /update- /update-
agent- skill- claude-
learnings learnings learnings
│ │ │
▼ ▼ ▼
agent- skill- CLAUDE.md
learnings learnings
.md .md
│
▼
同步至
agent文件工作流链：
会话揭示行为模式
│
▼
update-claude-learnings Skill（本Skill）
│
▼
CLAUDE.md已更新
│
▼
未来会话将受益于该规则Examples
示例
Example 1: Workflow Rule - Use Skills
示例1：工作流规则 - 使用Skill
Session Issue: Used instead of skill.
git add && git commit/commitLearning Extraction:
- Category: Workflow Rules
- Section: Use Available Skills
- Learning: "Use instead of manual
/commit"git add && git commit
Result:
Added to CLAUDE.md under
## Workflow Rules > ### Use Available Skills会话问题： 使用而非 Skill。
git add && git commit/commit经验提取：
- 分类：工作流规则
- 章节：使用可用Skill
- 经验："Use instead of manual
/commit"git add && git commit
结果：
添加至CLAUDE.md的章节
## 工作流规则 > ### 使用可用SkillExample 2: Session Management
示例2：会话管理
Session Issue: Complex task completed but no checkpoints provided.
Learning Extraction:
- Category: Session Management
- Section: Session Management
- Learning: "Provide checkpoint summaries every 3-5 edits on complex tasks"
Result:
Added to CLAUDE.md under
## Workflow Rules > ### Session Management会话问题： 完成复杂任务但未提供检查点。
经验提取：
- 分类：会话管理
- 章节：会话管理
- 经验："Provide checkpoint summaries every 3-5 edits on complex tasks"
结果：
添加至CLAUDE.md的章节
## 工作流规则 > ### 会话管理Example 3: Project-Specific Behavior
示例3：项目特定行为
Session Issue: Edited files in without running learnings sync.
.claude/agents/Learning Extraction:
- Category: Behavioral Patterns
- Section: Behavioral Patterns
- Learning: "After editing agent files, run to sync global learnings"
/update-agent-learnings
Result:
Added to CLAUDE.md under
## Behavioral Patterns会话问题： 编辑中的文件但未运行经验同步。
.claude/agents/经验提取：
- 分类：行为模式
- 章节：行为模式
- 经验："After editing agent files, run to sync global learnings"
/update-agent-learnings
结果：
添加至CLAUDE.md的章节
## 行为模式Example 4: Scope Redirect
示例4：范围重定向
Session Issue: User suggests adding "Run tests after code changes"
Analysis: This applies to subagents writing code, not main Claude Code behavior.
Action: Redirect to instead of adding to CLAUDE.md.
/update-agent-learnings会话问题： 用户建议添加"Run tests after code changes"
分析： 这适用于编写代码的子Agent，而非主Claude Code行为。
操作： 重定向至，而非添加至CLAUDE.md。
/update-agent-learnings