self-learning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

The self-learning skill automatically discovers, understands, and persists project context across sessions. It builds a mental model of the codebase, tech stack, conventions, and team preferences by scanning actual project artifacts. Without self-learning, every session starts from zero — with it, the agent accumulates institutional knowledge that improves accuracy and reduces errors over time.

Announce at start: "I'm using the self-learning skill to understand this project."

自学习技能可跨会话自动发现、理解并持久化存储项目上下文。它通过扫描实际项目构件，构建关于代码库、技术栈、规范约定和团队偏好的心智模型。如果没有自学习能力，每次会话都将从零开始——有了它，Agent可以积累体系化知识，随着时间推移提升准确性并减少错误。

启动时声明： "I'm using the self-learning skill to understand this project."

Phase 1: Trigger Identification

阶段1：触发条件识别

Determine which trigger activated this skill:

Trigger	Context	Action
New project	No memory files exist	Full discovery (Phases 2-5)
Unfamiliar area	Working in unknown part of codebase	Targeted discovery (Phase 2-3 for that area)
User correction	User says "that's wrong" or corrects an assumption	Correction protocol (Phase 6)
Explicit `/learn`	User invokes the command	Full discovery (Phases 2-5)
Session start	Memory files exist but may be stale	Load and validate memory (Phase 7)

STOP: Identify your trigger before proceeding. Different triggers require different phases.

确定激活该技能的触发条件：

触发条件	上下文	操作
新项目	不存在内存文件	全面发现（阶段2-5）
不熟悉的代码区域	正在处理代码库中未知的部分	定向发现（仅针对该区域执行阶段2-3）
用户纠正	用户指出"that's wrong"或纠正某个假设	纠正协议（阶段6）
显式调用 `/learn`	用户执行该命令	全面发现（阶段2-5）
会话启动	存在内存文件但可能已过时	加载并验证内存（阶段7）

停止：继续操作前先确认你的触发条件，不同触发条件需要执行不同阶段。

Phase 2: Project Structure Scan

阶段2：项目结构扫描

Use Explore agents to examine these files in order of priority:

File/Directory	What It Reveals	Priority
`package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `composer.json`	Tech stack, dependencies, scripts	Critical
`README.md` / `CLAUDE.md` / `AGENTS.md`	Project purpose, conventions, rules	Critical
Directory structure (top 2 levels)	Architecture pattern (monorepo, MVC, hexagonal, etc.)	Critical
`tsconfig.json` / `eslint.config.*` / `.prettierrc` / `phpstan.neon`	Coding standards, strictness level	High
`.gitignore`	What is excluded, deployment hints	High
`docker-compose.yml` / `Dockerfile`	Infrastructure, services	Medium
`.github/workflows/` / `.gitlab-ci.yml`	CI/CD setup, required checks	Medium
`.env.example`	Environment variables, external services	Medium
`specs/` / `docs/`	Existing specifications and documentation	Medium

Action: For each file found, extract key facts. Do NOT read every file — scan strategically.

STOP: Complete the structure scan before analyzing code patterns.

使用Explore Agent按优先级检查以下文件：

文件/目录	可获取的信息	优先级
`package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `composer.json`	技术栈、依赖、脚本	极高
`README.md` / `CLAUDE.md` / `AGENTS.md`	项目用途、规范、规则	极高
目录结构（前2层）	架构模式（monorepo、MVC、六边形架构等）	极高
`tsconfig.json` / `eslint.config.*` / `.prettierrc` / `phpstan.neon`	编码规范、严格级别	高
`.gitignore`	要排除的内容、部署提示	高
`docker-compose.yml` / `Dockerfile`	基础设施、服务	中
`.github/workflows/` / `.gitlab-ci.yml`	CI/CD配置、必填检查项	中
`.env.example`	环境变量、外部服务	中
`specs/` / `docs/`	现有规范和文档	中

操作： 对每个找到的文件提取关键信息。不要逐字读取所有文件——进行策略性扫描。

停止：完成结构扫描后再分析代码模式。

Phase 3: Code Pattern Analysis

阶段3：代码模式分析

Examine 3-5 representative files to identify patterns:

Pattern Category	What to Look For	Example Indicators
Naming conventions	Variable/function/file naming	camelCase, snake_case, kebab-case, PascalCase
Import/export	Module organization	Barrel exports, relative vs absolute paths, path aliases
Error handling	How failures are managed	try/catch, Result types, error boundaries, custom exceptions
Testing patterns	Test framework and style	File naming ( `.test.ts` vs `.spec.ts` ), structure (describe/it vs test)
State management	How data flows	Redux, Zustand, Context, Vuex, Pinia, Livewire
API patterns	Communication style	REST, GraphQL, tRPC, RPC, WebSocket
Database access	Data layer approach	ORM (Prisma, Eloquent, TypeORM), raw SQL, query builder
Component patterns	UI structure	Atomic design, feature folders, co-located styles

Action: Open 3-5 files from different areas of the codebase. Record observed patterns with specific examples.

检查3-5个代表性文件来识别模式：

模式类别	需要查找的内容	示例标识
命名规范	变量/函数/文件命名	camelCase, snake_case, kebab-case, PascalCase
导入/导出	模块组织	桶导出、相对路径与绝对路径、路径别名
错误处理	故障处理方式	try/catch, Result types, error boundaries, custom exceptions
测试模式	测试框架和风格	文件命名（ `.test.ts` vs `.spec.ts` ）、结构（describe/it vs test）
状态管理	数据流转方式	Redux, Zustand, Context, Vuex, Pinia, Livewire
API模式	通信风格	REST, GraphQL, tRPC, RPC, WebSocket
数据库访问	数据层实现方式	ORM（Prisma, Eloquent, TypeORM）、原生SQL、查询构建器
组件模式	UI结构	原子设计、功能文件夹、就近样式

操作： 打开代码库不同区域的3-5个文件，记录观察到的模式并附上具体示例。

Phase 4: Git History Analysis

阶段4：Git历史分析

bash

git log --oneline -20          # Recent commits — development velocity, commit style
git shortlog -sn -20           # Active contributors
git branch -a                  # Branching strategy
git log --diff-filter=A --name-only --pretty=format: -10 | head -30  # Recently added files

Extract: Development velocity, commit message conventions, branching strategy, active areas.

STOP: Complete all discovery phases before persisting to memory.

bash

git log --oneline -20          # Recent commits — development velocity, commit style
git shortlog -sn -20           # Active contributors
git branch -a                  # Branching strategy
git log --diff-filter=A --name-only --pretty=format: -10 | head -30  # Recently added files

提取信息： 开发速度、commit信息规范、分支策略、活跃开发区域。

停止：完成所有发现阶段后再持久化到内存。

Phase 5: Persist to Memory

阶段5：持久化到内存

Update the following memory files (create if they do not exist, append if they do):

更新以下内存文件（如果不存在则创建，存在则追加内容）：

memory/project-context.md

memory/project-context.md

markdown

undefined

markdown

undefined

Project Context

项目上下文

Purpose

用途

[What this project does, who it is for]

[项目的功能、目标用户]

Tech Stack

技术栈

Language: [e.g., TypeScript 5.x]
Framework: [e.g., Next.js 15]
Database: [e.g., PostgreSQL via Prisma]
Testing: [e.g., Vitest + Playwright]
CI/CD: [e.g., GitHub Actions]

编程语言：[例如 TypeScript 5.x]
框架：[例如 Next.js 15]
数据库：[例如基于Prisma的PostgreSQL]
测试：[例如 Vitest + Playwright]
CI/CD：[例如 GitHub Actions]

Architecture

架构

[e.g., Monorepo with apps/ and packages/] [Key directories and their purposes]

[例如包含apps/和packages/目录的monorepo] [核心目录及其用途]

Key Dependencies

核心依赖

[Critical libraries and their roles]

undefined

[关键库及其作用]

undefined

memory/learned-patterns.md

memory/learned-patterns.md

markdown

undefined

markdown

undefined

Learned Patterns

已学习的模式

Naming Conventions

命名规范

[What was observed with specific examples]

[观察到的规范及具体示例]

Code Organization

代码组织

[Import patterns, file structure, module boundaries]

[导入模式、文件结构、模块边界]

Error Handling

错误处理

[How errors are handled in this project with examples]

[本项目的错误处理方式及示例]

Testing Approach

测试方案

[Framework, patterns, naming, coverage expectations]

undefined

[框架、模式、命名、覆盖率要求]

undefined

memory/user-preferences.md

memory/user-preferences.md

markdown

undefined

markdown

undefined

User Preferences

用户偏好

Communication Style

沟通风格

[Terse? Detailed? Prefers code over explanation?]

[简洁？详细？偏好代码胜过文字解释？]

Workflow Preferences

工作流偏好

[PR workflow? Branch naming? Commit style?]

[PR工作流？分支命名？commit风格？]

Review Preferences

评审偏好

[What they focus on in reviews?]

undefined

[他们在评审中关注的内容？]

undefined

memory/decisions-log.md

memory/decisions-log.md

markdown

undefined

markdown

undefined

Decisions Log

决策日志

YYYY-MM-DD: [Decision Title]

YYYY-MM-DD: [决策标题]

Decision: [What was decided] Context: [Why this came up] Rationale: [Why this was chosen over alternatives] Alternatives considered: [What else was considered]

---

决策： [决策内容] 背景： [该决策的触发原因] 理由： [选择该方案而非其他方案的原因] 考虑过的替代方案： [其他备选方案]

---

Phase 6: Correction Protocol

阶段6：纠正协议

When the user corrects an assumption:

Acknowledge the correction immediately — do not defend the wrong assumption
Identify which memory file should be updated
Update the memory file with the correction, including date and context
Apply the correction to current work immediately
Propagate — check if the correction invalidates other assumptions in memory

Correction Type	Memory File to Update	Example
Naming convention wrong	`learned-patterns.md`	"We use snake_case, not camelCase"
Tech stack wrong	`project-context.md`	"We use Vitest, not Jest"
Workflow preference	`user-preferences.md`	"Always create PRs, never push to main"
Architecture misunderstanding	`project-context.md`	"That is a microservice, not a monolith"
Decision context	`decisions-log.md`	"We chose X because of Y, not Z"

Do NOT skip the memory update. Corrections that are not persisted will be repeated.

当用户纠正某个假设时：

立即确认收到纠正——不要为错误的假设辩解
确定需要更新的内存文件
更新内存文件，记录纠正内容，包括日期和上下文
立即将纠正内容应用到当前工作中
同步检查——确认该纠正是否会导致内存中其他假设失效

纠正类型	需要更新的内存文件	示例
命名规范错误	`learned-patterns.md`	"我们使用snake_case，不是camelCase"
技术栈错误	`project-context.md`	"我们使用Vitest，不是Jest"
工作流偏好	`user-preferences.md`	"永远要创建PR，不要直接push到main分支"
架构理解错误	`project-context.md`	"那是微服务，不是单体应用"
决策背景	`decisions-log.md`	"我们选择X是因为Y，不是Z"

不要跳过内存更新步骤。没有持久化的纠正内容会导致后续重复犯错。

Phase 7: Session Start — Memory Validation

阶段7：会话启动——内存验证

When memory files already exist:

Load all memory files from
```
memory/
```
directory
Check
```
Last updated
```
dates — flag anything older than 30 days
Spot-check 2-3 facts against current codebase (e.g., does
```
package.json
```
still list the same framework?)
If discrepancies found, run a targeted re-scan of the changed area
Update stale entries with current information

当内存文件已存在时：

加载
```
memory/
```
目录下的所有内存文件
检查
```
最后更新
```
日期——标记所有超过30天的内容
抽样检查2-3个事实是否匹配当前代码库（例如：
```
package.json
```
中列出的框架是否和之前记录的一致？）
如果发现差异，对变更区域执行定向重扫描
用当前信息更新过时的条目

Decision Table: Discovery Depth

决策表：发现深度

Situation	Discovery Depth	Time Budget
Brand new project, no memory files	Full (all phases)	3-5 minutes
New area of known project	Targeted (Phase 2-3 for that area only)	1-2 minutes
User correction	Correction protocol only (Phase 6)	30 seconds
Session start with existing memory	Validation only (Phase 7)	1 minute
Major refactor detected (many changed files)	Full re-scan	3-5 minutes

场景	发现深度	时间预算
全新项目，没有内存文件	全面（所有阶段）	3-5分钟
已知项目的新区域	定向（仅针对该区域执行阶段2-3）	1-2分钟
用户纠正	仅执行纠正协议（阶段6）	30秒
会话启动，已有内存文件	仅验证（阶段7）	1分钟
检测到大规模重构（大量文件变更）	全面重扫描	3-5分钟

Anti-Patterns / Common Mistakes

反模式/常见错误

What NOT to Do	Why It Fails	What to Do Instead
Read every file in the project	Wastes context window, slow	Scan strategically: config files first, then 3-5 representative code files
Assume conventions from one file	One file may be an outlier	Verify patterns across 2+ files before persisting
Overwrite memory files completely	Loses historical context and user corrections	Append or update specific sections, preserve history
Skip git history	Misses development velocity and team patterns	Always check recent commits and contributors
Persist guesses as facts	Poisons future sessions with wrong context	Only persist observations backed by evidence
Ignore user corrections	Repeats the same mistakes	Corrections override observations immediately
Deep-dive into implementation details	Loses the forest for the trees	Focus on patterns and conventions, not specific logic
Skip memory validation on session start	Uses stale context	Always spot-check memory against current codebase

禁止操作	失败原因	正确做法
读取项目中的所有文件	浪费上下文窗口，速度慢	策略性扫描：优先看配置文件，然后看3-5个代表性代码文件
仅凭单个文件推断规范	单个文件可能是个例	持久化前在2个以上文件中验证模式
完全覆盖内存文件	丢失历史上下文和用户纠正内容	追加或更新特定部分，保留历史记录
跳过Git历史分析	遗漏开发速度和团队模式信息	始终检查近期commit和贡献者
将猜测作为事实持久化	错误上下文会影响后续会话	仅持久化有证据支撑的观察结果
忽略用户纠正	重复犯相同错误	纠正内容优先级高于观察结果，立即生效
深入研究实现细节	只见树木不见森林	关注模式和规范，而非具体逻辑
会话启动时跳过内存验证	使用过时的上下文	始终对照当前代码库抽样检查内存内容

Anti-Rationalization Guards

反合理化防护

Thought	Reality
"I already know this framework"	You do not know THIS project's conventions. Scan.
"The memory files are recent enough"	Spot-check anyway. Code changes fast.
"This correction is minor"	Minor corrections prevent major errors. Persist it.
"I will remember this without writing it down"	You will not. Sessions are independent. Persist to memory.
"Scanning will take too long"	Not scanning leads to wrong assumptions that take longer to fix.

Do NOT skip memory persistence. If you discovered it, write it down.

想法	实际情况
"我已经了解这个框架了"	你不了解这个项目的规范，去扫描。
"内存文件足够新"	还是抽样检查一下，代码迭代很快。
"这个纠正不重要"	小纠正能避免大错误，把它记下来。
"我不用写下来也能记住"	你记不住的，会话之间是独立的，持久化到内存。
"扫描太费时间了"	不扫描会导致错误假设，后续修复花费的时间更长。

不要跳过内存持久化步骤，只要你发现了就记下来。

Integration Points

集成点

Skill	Relationship
`using-toolkit`	Triggers self-learning at session start
`brainstorming`	Loads project context before idea generation
`planning`	Uses learned patterns to propose consistent approaches
`code-review`	Checks code against learned conventions
`auto-improvement`	Records discovery effectiveness metrics
`resilient-execution`	Failure patterns inform future approach selection

技能	关系
`using-toolkit`	会话启动时触发自学习
`brainstorming`	生成想法前加载项目上下文
`planning`	使用已学习的模式提出一致的实现方案
`code-review`	对照已学习的规范检查代码
`auto-improvement`	记录发现效果指标
`resilient-execution`	故障模式为后续方案选择提供参考

Concrete Examples

具体示例

Discovery Command Sequence

发现命令序列

bash

undefined

bash

undefined

Step 1: Identify tech stack

cat package.json | head -50

or

cat composer.json | head -50

or

cat pyproject.toml

Step 2: Check project structure

ls -la ls -la src/ || ls -la app/ || ls -la lib/

Step 3: Examine coding standards

cat tsconfig.json 2>/dev/null || cat phpstan.neon 2>/dev/null cat .eslintrc* 2>/dev/null || cat .prettierrc* 2>/dev/null

Step 4: Git activity

git log --oneline -20 git shortlog -sn -20

undefined

git log --oneline -20 git shortlog -sn -20

undefined

Memory Update After Correction

纠正后的内存更新

markdown

undefined

markdown

undefined

2026-03-15: Naming Convention Correction

2026-03-15: 命名规范纠正

Previous assumption: Project uses camelCase for database columns Correction: Project uses snake_case for database columns (user corrected) Evidence: Checked

migrations/

directory — all columns use snake_case Updated: learned-patterns.md, Naming Conventions section

---

之前的假设： 项目数据库列使用camelCase命名 纠正内容： 项目数据库列使用snake_case命名（用户纠正） 证据： 检查

migrations/

目录——所有列都使用snake_case命名 更新文件： learned-patterns.md，命名规范部分

---

Key Principles

核心原则

Observe, do not assume — base learnings on evidence from the codebase
Incremental updates — append to memory files, do not overwrite
Verify before persisting — double-check observations with 2+ examples
Respect corrections — user corrections override observations immediately
Stay current — re-scan when significant changes occur

观察而非假设 —— 基于代码库中的证据得出学习结论
增量更新 —— 向内存文件追加内容，不要覆盖
持久化前验证 —— 用2个以上示例交叉验证观察结果
尊重纠正内容 —— 用户纠正内容优先级立即高于观察结果
保持内容最新 —— 发生重大变更时重新扫描

Skill Type

技能类型

RIGID — Discovery phases must be followed in order. Memory persistence is mandatory. Corrections must be recorded immediately. Do not skip phases or rationalize away the need to scan.

RIGID —— 必须按顺序执行发现阶段，内存持久化是强制要求，必须立即记录纠正内容，不要跳过任何阶段，也不要合理化逃避扫描的必要性。