Back to Details

learn-and-improve

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Learn and Improve

学习与优化

Analyze friction in the current session and propose targeted improvements to Claude Code configuration.
分析当前会话中的使用障碍，针对Claude Code配置提出定向优化方案。

Workflow

工作流

Step 1: Understand the Problem

步骤1：理解问题

Ask the user what went wrong. If they've already described the issue, confirm your understanding.
Use 
AskUserQuestion
to clarify:
  • What happened? (e.g., "skill X asked for permission to run Y")
  • What should have happened? (e.g., "it should just run without asking")
  • How often does this occur? (one-off vs recurring)
询问用户遇到了什么问题。如果用户已经描述了问题，确认你的理解是否正确。
使用
AskUserQuestion
来明确信息：
  • 发生了什么？（例如：「skill X 请求权限运行Y」）
  • 预期应该发生什么？（例如：「应该直接运行，不需要询问」）
  • 这种情况发生的频率？（偶发 vs 复现）

Step 2: Gather Diagnostic Context

步骤2：收集诊断上下文

Investigate the current configuration by reading these files (read only what exists):
Settings (permissions, hooks, env):
  • ~/.claude/settings.json
    (user-level)
  • .claude/settings.json
    (project-level, shared)
  • .claude/settings.local.json
    (project-level, local)
Memory (CLAUDE.md hierarchy):
  • ~/.claude/CLAUDE.md
    (user-level)
  • ./CLAUDE.md
    or 
    ./.claude/CLAUDE.md
    (project-level)
  • ./CLAUDE.local.md
    (local overrides)
  • ./.claude/rules/*.md
    (modular rules)
Auto memory:
  • ~/.claude/projects/*/memory/MEMORY.md
    for the current project
Plugins & skills:
  • .claude-plugin/marketplace.json
    (if in a plugin repo)
  • Installed plugins: 
    ~/.claude/plugins/cache/
    (list directories)
  • Installed marketplaces: 
    ~/.claude/plugins/marketplaces/
    (list directories)
MCP servers:
  • .mcp.json
    (project)
  • ~/.claude.json
    or 
    ~/.claude/mcp.json
    (user)
Also review the conversation history for:
  • Tool calls that were blocked or required permission prompts
  • Skills that were invoked (or should have been but weren't)
  • Agents that were spawned and their outcomes
  • Error messages or unexpected behavior
通过读取以下存在的文件来调查当前配置：
设置（权限、hooks、环境变量）：
  • ~/.claude/settings.json
    （用户级别）
  • .claude/settings.json
    （项目级别，共享）
  • .claude/settings.local.json
    （项目级别，本地）
记忆（CLAUDE.md层级）：
  • ~/.claude/CLAUDE.md
    （用户级别）
  • ./CLAUDE.md
    或 
    ./.claude/CLAUDE.md
    （项目级别）
  • ./CLAUDE.local.md
    （本地覆盖）
  • ./.claude/rules/*.md
    （模块化规则）
自动记忆：
  • 当前项目对应的
    ~/.claude/projects/*/memory/MEMORY.md
插件与skills：
  • .claude-plugin/marketplace.json
    （如果在插件仓库中）
  • 已安装插件：
    ~/.claude/plugins/cache/
    （列出目录）
  • 已安装市场：
    ~/.claude/plugins/marketplaces/
    （列出目录）
MCP服务器：
  • .mcp.json
    （项目级别）
  • ~/.claude.json
    或 
    ~/.claude/mcp.json
    （用户级别）
同时查看对话历史，确认以下信息：
  • 被阻止或需要权限弹窗的工具调用
  • 被调用（或应该被调用但未调用）的skills
  • 生成的agents及其执行结果
  • 错误信息或异常行为

Step 3: Identify the Root Cause

步骤3：定位根本原因

Common root causes and their fixes — see Improvement Types for full details.
SymptomLikely CauseFix Location
Permission prompt for a bash commandMissing 
allow
rule		settings.json 
permissions.allow
Permission prompt for file read/writeMissing path patternsettings.json 
permissions.allow
Skill not triggeringBad description triggersSkill SKILL.md frontmatter
Skill triggering on wrong tasksDescription too broadSkill SKILL.md frontmatter
Repeated instructions ignoredNot in CLAUDE.mdCLAUDE.md (appropriate level)
Convention not followed per-filetypeNo path-scoped rule
.claude/rules/
with paths frontmatter
Agent hitting permission wallsAgent lacks 
permissionMode
Agent frontmatter
MCP tool requiring permissionMissing MCP allow rulesettings.json 
permissions.allow
Hook not firingWrong matcher or eventsettings.json 
hooks
常见根本原因及其修复方案——完整详情请查看优化类型。
症状可能原因修复位置
执行bash命令弹出权限申请缺少
allow
规则		settings.json 
permissions.allow
读写文件弹出权限申请缺少路径匹配规则settings.json 
permissions.allow
Skill未触发触发描述配置错误Skill对应的SKILL.md头信息
Skill匹配了错误的任务描述范围过宽Skill对应的SKILL.md头信息
重复的指令被忽略未写入CLAUDE.md对应层级的CLAUDE.md
特定文件类型未遵循约定没有路径范围的规则带路径头信息的
.claude/rules/
配置
Agent遇到权限拦截Agent缺少
permissionMode
配置		Agent头信息
MCP工具需要权限申请缺少MCP允许规则settings.json 
permissions.allow
Hook未触发匹配规则或事件配置错误settings.json 
hooks

Step 4: Propose Improvements

步骤4：提出优化方案

In addition to fixing the reported issue, review the session for commands that were prompted for permission but are read-only and side-effect free (e.g., 
ls
, 
gh pr view
, 
git log
). Suggest permanently allowing these — at user level for read-only commands, project level for write commands. See Improvement Types for examples.
For each proposed improvement, present:
  1. What to change — the specific file and content
  2. Why — how this fixes the reported issue
  3. Who benefits — see the table below to explain the reach of the improvement
  4. Risk — any trade-offs (e.g., "this auto-allows all npm commands")
Explain the reach of each improvement type to help the user decide:
Improvement TypeBest ForWho Benefits
Skill fix (external plugin)Fixing behavior everyone hits — opens a PR upstreamAll users of the skill
Skill fix (personal skill)Your custom workflows across all projectsYou, all projects
Agent fix (external plugin)Agents that hit permission walls or use wrong modelAll users of the agent
User-level settingsPermission rules and preferences that apply everywhereYou, all projects
User-level CLAUDE.mdCoding conventions and instructions you always wantYou, all projects
Project-shared settingsTeam permissions and conventionsYour team, one project
Project-shared CLAUDE.mdArchitecture notes, project-specific patternsYour team, one project
Project-local settingsPersonal overrides for one projectJust you, one project
HookAutomating repetitive steps (formatting, tests, safety) — delegate to 
toolkit:claude-code-hook-development
skill for non-trivial hooks		Depends on scope
Project rules (
.claude/rules/
)		File-type-scoped conventions (API rules, test rules, frontend rules) — delegate to 
toolkit:claude-code-memory-and-rules
skill for setup		Your team, one project
User rules (
~/.claude/rules/
)		Personal conventions across all projectsJust you, all projects
Auto memorySession learnings that don't belong in CLAUDE.md — delegate to 
toolkit:claude-code-memory-and-rules
skill for setup		You, one project
When an improvement could live at multiple scopes, present the options and explain the trade-off — broader scope means more reuse but also more risk if the change is wrong.
除了修复用户反馈的问题之外，还要检查本次会话中那些需要权限申请但属于只读、无副作用的命令（例如
ls
、
gh pr view
、
git log
）。建议永久允许这类命令——只读命令在用户级别配置允许，写入命令在项目级别配置允许。示例请参考优化类型。
针对每个提出的优化方案，需要说明：
  1. 修改内容——具体的文件和调整的内容
  2. 原因——该调整如何解决反馈的问题
  3. 受益范围——参考下表说明优化的覆盖范围
  4. 风险——任何权衡取舍（例如：「该配置会自动允许所有npm命令」）
解释每个优化类型的覆盖范围，帮助用户决策：
优化类型适用场景受益范围
Skill修复（外部插件）修复所有用户都会遇到的行为问题——向上游提交PR该skill的所有用户
Skill修复（个人skill）适用于跨项目的自定义工作流你所有的项目
Agent修复（外部插件）解决Agent遇到权限拦截、使用错误模型的问题该agent的所有用户
用户级别设置适用于全局生效的权限规则和偏好你所有的项目
用户级别CLAUDE.md适用于你需要全局生效的编码约定和指令你所有的项目
项目共享设置团队权限和约定你的团队，单个项目
项目共享CLAUDE.md架构说明、项目特定规范你的团队，单个项目
项目本地设置单个项目的个人覆盖配置仅你自己，单个项目
Hook自动化重复步骤（格式化、测试、安全检查）——非简单Hook请使用
toolkit:claude-code-hook-development
skill开发		取决于配置范围
项目规则（
.claude/rules/
）		按文件类型生效的约定（API规则、测试规则、前端规则）——配置请使用
toolkit:claude-code-memory-and-rules
skill		你的团队，单个项目
用户规则（
~/.claude/rules/
）		跨项目的个人编码约定仅你自己，所有项目
自动记忆不需要写入CLAUDE.md的会话学习内容——配置请使用
toolkit:claude-code-memory-and-rules
skill		仅你自己，单个项目
当一个优化可以在多个层级配置时，列出所有选项并解释权衡——覆盖范围越广复用性越强，但如果配置错误风险也越高。

Step 5: Apply the Change

步骤5：应用修改

Apply the approved change to the correct file. After applying:
  1. Verify the file is valid JSON (for settings files) or valid markdown (for CLAUDE.md)
  2. Tell the user if a restart is needed (hooks require restart; skills/CLAUDE.md do not)
  3. If the fix is to an external skill or plugin, propose opening a PR instead
将已确认的修改应用到正确的文件中。应用后：
  1. 验证文件格式是否正确（设置文件需是有效JSON，CLAUDE.md需是有效markdown）
  2. 告知用户是否需要重启（hooks需要重启，skills/CLAUDE.md不需要）
  3. 如果是修复外部skill或插件的问题，建议提交PR而不是直接修改

Step 6: Record the Verified Improvement (ESSENTIAL)

步骤6：记录已验证的优化（必要步骤）

Every user-approved improvement is a verified data point. This skill is self-improving — each fix makes it better for the next person.
After the user confirms the improvement works, append a summary to Verified Improvements using this format:
markdown
undefined
每个用户确认生效的优化都是已验证的数据点。该技能具备自优化能力——每次修复都会让它在后续使用中表现更好。
用户确认优化生效后，按照以下格式将摘要追加到已验证优化中：
markdown
undefined

[Short title]

[简短标题]

  • Friction: [What went wrong]
  • Fix: [What was changed and where]
  • Scope: [Who benefits — e.g., "all users of toolkit:research"]

Keep entries concise (3 lines max). This log serves two purposes:
1. **Examples for future invocations** — Claude reads these to pattern-match similar problems faster
2. **Evidence for skill evolution** — patterns in the log reveal common friction that should be addressed in the skill itself or its references

If the log grows beyond ~30 entries, consolidate repeated patterns into the root cause table in Step 3 and remove the individual entries.
  • 问题：[遇到的使用障碍]
  • 修复方案：[修改的内容和位置]
  • 覆盖范围：[受益群体——例如：「toolkit:research的所有用户」]

保持条目简洁（最多3行）。该日志有两个作用：
1. **为后续调用提供示例**——Claude会读取这些内容，更快匹配相似问题
2. **为技能迭代提供依据**——日志中的规律可以暴露普遍存在的使用障碍，便于优化技能本身或其参考文档

如果日志条目超过约30条，将重复出现的模式合并到步骤3的根本原因表格中，并删除对应的单独条目。

Important Constraints

重要约束

  • Never modify managed/enterprise settings — those are IT-controlled
  • Always confirm before writing — show the exact change first
  • Consider the reach — explain who benefits from each improvement type so the user can choose the right scope
  • Preserve existing content — merge into existing settings, don't overwrite
  • Settings format: permission rules use 
    Tool(pattern)
    syntax (e.g., 
    Bash(npm run *)
    )
  • 绝不修改托管/企业级设置——这些是IT管控的配置
  • 写入前务必确认——先展示准确的修改内容
  • 考虑覆盖范围——解释每个优化类型的受益群体，方便用户选择合适的层级
  • 保留现有内容——合并到现有设置中，不要覆盖
  • 设置格式：权限规则使用
    Tool(pattern)
    语法（例如：
    Bash(npm run *)
    ）

Quick Reference

快速参考

For the full catalog of improvement types and examples, see:
  • Improvement Types — all configuration levers with examples
  • Diagnostic Checklist — systematic investigation steps
完整的优化类型目录和示例请查看：
  • 优化类型——所有配置项及示例
  • 诊断检查清单——系统化的调查步骤