Back to Details

self-improvement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

自改进

Self-Improvement

把一次性对话中的高价值经验，转成项目内可复用资产。
Convert high-value experiences from one-time conversations into reusable assets within the project.

Quick Reference

Quick Reference

情况动作
命令/工具失败记录到 
.learnings/ERRORS.md
用户纠正你记录到 
.learnings/LEARNINGS.md
，类别 
correction
用户要求缺失能力记录到 
.learnings/FEATURE_REQUESTS.md
外部 API 失败记录到 
.learnings/ERRORS.md
，含集成细节
知识已过时记录到 
.learnings/LEARNINGS.md
，类别 
knowledge_gap
发现更好做法记录到 
.learnings/LEARNINGS.md
，类别 
best_practice
与已有条目相似用 
See Also
关联，考虑提升优先级
广泛适用的经验提升到 
CLAUDE.md
/ 
AGENTS.md
ScenarioAction
Command/Tool FailureRecord to 
.learnings/ERRORS.md
User Corrected YouRecord to 
.learnings/LEARNINGS.md
, category 
correction
User Requests Missing CapabilityRecord to 
.learnings/FEATURE_REQUESTS.md
External API FailureRecord to 
.learnings/ERRORS.md
, including integration details
Outdated KnowledgeRecord to 
.learnings/LEARNINGS.md
, category 
knowledge_gap
Better Practice DiscoveredRecord to 
.learnings/LEARNINGS.md
, category 
best_practice
Similar to Existing EntryLink with 
See Also
, consider raising priority
Widely Applicable ExperienceElevate to 
CLAUDE.md
/ 
AGENTS.md

文件结构

File Structure

text
.learnings/
├── LEARNINGS.md
├── ERRORS.md
└── FEATURE_REQUESTS.md
text
.learnings/
├── LEARNINGS.md
├── ERRORS.md
└── FEATURE_REQUESTS.md

何时记录

When to Record

优先记录这些情况：
  1. 用户纠正了你的判断、假设或实现方式
  2. 工具、命令、运行环境出现了非显然失败
  3. 用户要求当前系统不直接支持的能力
  4. 你发现了值得复用的项目约束、工作流或最佳实践
  5. 你的知识已过时或与实际行为不符
不要记录这些情况：
  1. 明显且一次性的错误
  2. 无需复盘即可解决的小问题
  3. 与当前项目无关的泛泛常识
Prioritize recording in these situations:
  1. Users corrected your judgment, assumptions, or implementation methods
  2. Non-obvious failures occurred in tools, commands, or runtime environments
  3. Users requested capabilities not directly supported by the current system
  4. You discovered reusable project constraints, workflows, or best practices
  5. Your knowledge is outdated or inconsistent with actual behavior
Do not record these situations:
  1. Obvious one-time errors
  2. Minor issues that can be resolved without review
  3. General common sense unrelated to the current project

记录原则

Recording Principles

  1. 只保留高信号信息，避免把 
    .learnings/
    变成噪音堆积区
  2. 先写"为什么以后还会有用"，再写"这次发生了什么"
  3. 如果是错误，明确复现线索和建议修复方向
  4. 如果是用户纠正，明确原假设哪里错了
  5. 记录前先搜索已有条目，重复的用 See Also 关联
  6. 如果模式已经稳定，考虑提升到 
    AGENTS.md
    或抽出新 skill
  1. Only retain high-signal information, avoid turning 
    .learnings/
    into a noise accumulation area
  2. First write "why it will be useful in the future", then write "what happened this time"
  3. If it's an error, clarify reproduction clues and suggested repair directions
  4. If it's a user correction, clarify where the original assumption was wrong
  5. Search existing entries before recording, link duplicates with See Also
  6. If the pattern has stabilized, consider elevating to 
    AGENTS.md
    or extracting a new skill

记录格式

Recording Format

Learning

Learning

markdown
undefined
markdown
undefined

[LRN-YYYYMMDD-XXXXXX] correction | knowledge_gap | best_practice

[LRN-YYYYMMDD-XXXXXX] correction | knowledge_gap | best_practice

Logged: 2026-03-23T10:00:00+00:00 Priority: low | medium | high | critical Status: pending Area: frontend | backend | infra | tests | docs | config | runtime
Logged: 2026-03-23T10:00:00+00:00 Priority: low | medium | high | critical Status: pending Area: frontend | backend | infra | tests | docs | config | runtime

Summary

Summary

一句话说明学到了什么
One-sentence explanation of what was learned

Details

Details

说明当时的错误假设、触发条件和正确做法
Explain the wrong assumption at the time, trigger conditions, and correct approach

Suggested Action

Suggested Action

以后应如何避免再次犯错
How to avoid making the same mistake in the future

Metadata

Metadata

  • Source: user_feedback | error | conversation
  • Related Files: path/to/file.py
  • Tags: tag1, tag2
  • See Also: LRN-20260320-001 (如果与已有条目相关)
  • Pattern-Key: correction.api_format (可选，用于重复模式追踪)
  • Recurrence-Count: 1 (可选)
undefined
  • Source: user_feedback | error | conversation
  • Related Files: path/to/file.py
  • Tags: tag1, tag2
  • See Also: LRN-20260320-001 (if related to existing entry)
  • Pattern-Key: correction.api_format (optional, for repeating pattern tracking)
  • Recurrence-Count: 1 (optional)
undefined

Error

Error

markdown
undefined
markdown
undefined

[ERR-YYYYMMDD-XXXXXX] auto_logged_error

[ERR-YYYYMMDD-XXXXXX] auto_logged_error

Logged: 2026-03-23T10:00:00+00:00 Priority: medium | high Status: pending Area: runtime
Logged: 2026-03-23T10:00:00+00:00 Priority: medium | high Status: pending Area: runtime

Summary

Summary

一句话说明哪里失败了
One-sentence explanation of where the failure occurred

Error

Error

text
具体错误内容
text
Specific error content

Context

Context

  • Step: 3
  • Tool: 
    bash
  • Task: 当前任务摘要
  • Step: 3
  • Tool: 
    bash
  • Task: Current task summary

Suggested Fix

Suggested Fix

说明后续应怎么复盘或修正
Explain how to review or correct it later

Metadata

Metadata

  • Reproducible: yes | no | unknown
  • Related Files: N/A
  • Pattern-Key: tool_error.bash (可选)
  • Recurrence-Count: 2 (可选)
undefined
  • Reproducible: yes | no | unknown
  • Related Files: N/A
  • Pattern-Key: tool_error.bash (optional)
  • Recurrence-Count: 2 (optional)
undefined

Feature Request

Feature Request

markdown
undefined
markdown
undefined

[FEAT-YYYYMMDD-XXXXXX] capability_name

[FEAT-YYYYMMDD-XXXXXX] capability_name

Logged: 2026-03-23T10:00:00+00:00 Priority: medium Status: pending Area: runtime
Logged: 2026-03-23T10:00:00+00:00 Priority: medium Status: pending Area: runtime

Requested Capability

Requested Capability

用户需要什么能力
What capability the user needs

User Context

User Context

为什么需要它
Why they need it

Complexity Estimate

Complexity Estimate

simple | medium | complex
simple | medium | complex

Suggested Implementation

Suggested Implementation

可行的最小实现思路
Feasible minimal implementation idea

Metadata

Metadata

  • Frequency: first_time | recurring
  • Related Features: N/A
undefined
  • Frequency: first_time | recurring
  • Related Features: N/A
undefined

条目生命周期

Entry Lifecycle

Status含义
pending
新记录，待处理
in_progress
正在处理中
resolved
已修复/已解决
promoted
已提升到 CLAUDE.md / AGENTS.md / 新 skill
wont_fix
决定不处理（在 Resolution 中说明原因）
解决条目时，追加 Resolution 块：
markdown
undefined
StatusMeaning
pending
New record, pending processing
in_progress
Being processed
resolved
Fixed/resolved
promoted
Elevated to CLAUDE.md / AGENTS.md / new skill
wont_fix
Decision not to process (explain reason in Resolution)
When resolving an entry, append a Resolution block:
markdown
undefined

Resolution

Resolution

  • Resolved: 2026-03-24T09:00:00Z
  • Commit/PR: abc123 or #42
  • Notes: 简述做了什么
undefined
  • Resolved: 2026-03-24T09:00:00Z
  • Commit/PR: abc123 or #42
  • Notes: Brief description of what was done
undefined

重复模式检测

Repeating Pattern Detection

记录前先搜索已有条目：
bash
grep -r "keyword" .learnings/
如果找到相似条目：
  1. 用 
    See Also
    关联
  2. 考虑提升优先级
  3. 如果 Recurrence-Count >= 3，强烈建议提升到项目规则
Search existing entries before recording:
bash
grep -r "keyword" .learnings/
If similar entries are found:
  1. Link with 
    See Also
  2. Consider raising priority
  3. If Recurrence-Count >= 3, strongly recommend elevating to project rules

Priority 指引

Priority Guidelines

Priority适用场景
critical
阻塞核心功能、数据丢失风险、安全问题
high
显著影响、常见工作流受阻、反复出现
medium
中等影响、有 workaround
low
轻微不便、边缘场景
PriorityApplicable Scenarios
critical
Blocks core functionality, risk of data loss, security issues
high
Significant impact, common workflows blocked, recurring issues
medium
Moderate impact, has workaround
low
Minor inconvenience, edge cases

Area 标签

Area Tags

Area范围
frontend
UI、组件、客户端代码
backend
API、服务、服务端代码
infra
CI/CD、部署、Docker、云
tests
测试文件、测试工具
docs
文档、注释
config
配置文件、环境变量
runtime
Agent 运行时、工具执行
AreaScope
frontend
UI, components, client-side code
backend
APIs, services, server-side code
infra
CI/CD, deployment, Docker, cloud
tests
Test files, testing tools
docs
Documentation, comments
config
Configuration files, environment variables
runtime
Agent runtime, tool execution

提升路径

Elevation Path

当某条 learning 被多次验证、具有跨任务价值时：
Learning 类型提升目标示例
项目约定
CLAUDE.md
"包管理器用 uv，不要用 pip"
工作流规则
AGENTS.md
"API 变更后必须重新生成客户端"
可复用模式新 skill复杂到需要专门指导的模式
提升后更新原条目 Status 为 
promoted
，并注明 
**Promoted**: CLAUDE.md
。
When a learning has been verified multiple times and has cross-task value:
Learning TypeElevation TargetExample
Project Convention
CLAUDE.md
"Use uv as package manager, not pip"
Workflow Rule
AGENTS.md
"Must regenerate client after API changes"
Reusable PatternNew skillPatterns complex enough to require dedicated guidance
After elevation, update the original entry's Status to 
promoted
and note 
**Promoted**: CLAUDE.md
.

Skill 提取标准

Skill Extraction Criteria

当 learning 满足以下任一条件时，可以提取为独立 skill：
  • 有 2+ 条 See Also 关联（反复出现）
  • Status 为 resolved 且修复方案经过验证
  • 非显而易见，需要实际调试才能发现
  • 不限于特定项目，跨代码库可用
  • 用户明确要求 "把这个存为 skill"
A learning can be extracted as an independent skill if it meets any of the following conditions:
  • Has 2+ See Also links (recurring occurrence)
  • Status is resolved and the fix has been verified
  • Non-obvious, requires actual debugging to discover
  • Not limited to specific projects, usable across codebases
  • User explicitly requests "save this as a skill"

与原生 Hook 的关系

Relationship with Native Hook

项目内的 
SelfImprovementHook
自动做这些事：
  1. 运行前提醒你在必要时使用本 skill
  2. 工具失败时自动往 
    ERRORS.md
    记一条基础记录
  3. 同一工具反复失败时自动提升优先级并追踪 Pattern-Key
  4. 用户 reject/edit 反馈时自动往 
    LEARNINGS.md
    记录
  5. feature_request 反馈时自动往 
    FEATURE_REQUESTS.md
    记录
自动记录只是保底。真正高质量的 learning 仍然需要你在任务结束前主动整理。
The project's 
SelfImprovementHook
automatically performs these actions:
  1. Reminds you to use this skill when necessary before running
  2. Automatically records a basic entry in 
    ERRORS.md
    when a tool fails
  3. Automatically raises priority and tracks Pattern-Key when the same tool fails repeatedly
  4. Automatically records to 
    LEARNINGS.md
    when user rejects/edits feedback
  5. Automatically records to 
    FEATURE_REQUESTS.md
    when feature_request feedback is received
Automatic recording is only a safety net. Truly high-quality learning still requires active organization by you before task completion.

定期回顾

Regular Review

在以下时机回顾 
.learnings/
：
  • 开始新的大型任务前
  • 完成一个功能后
  • 在有历史 learning 的区域工作时
bash
grep -h "Status\*\*: pending" .learnings/*.md | wc -l
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["
Review 
.learnings/
at these times:
  • Before starting a new large task
  • After completing a feature
  • When working in an area with historical learnings
bash
grep -h "Status\*\*: pending" .learnings/*.md | wc -l
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["