self-learning

概述

自学习技能会自动发现、理解并跨会话保存项目上下文。它通过扫描实际项目资料，构建关于代码库、技术栈、惯例和团队偏好的心智模型。没有自学习，每次会话都从零开始；借助自学习，Agent 会积累组织知识，随着时间推移提高准确性并减少错误。

开始时宣布：“我正在使用自学习技能来了解这个项目。”

---

阶段 1：触发条件识别

确定是哪个触发条件激活了此技能：

触发条件	上下文	操作
新项目	不存在记忆文件	全面发现（阶段 2-5）
不熟悉的区域	正在处理代码库中未知的部分	定向发现（针对该区域执行阶段 2-3）
用户纠正	用户表示“这不对”或纠正某个假设	纠正流程（阶段 6）
显式执行 /learn	用户调用该命令	全面发现（阶段 2-5）
会话开始	记忆文件存在，但可能已过时	加载并验证记忆（阶段 7）

停止：继续之前先识别触发条件。不同的触发条件需要执行不同的阶段。

---

阶段 2：项目结构扫描

使用 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/	现有规范和文档	中

操作： 对找到的每个文件提取关键信息。不要读取每个文件，应有策略地扫描。

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

---

阶段 3：代码模式分析

检查 3-5 个有代表性的文件，识别代码模式：

模式类别	观察内容	示例指标
命名惯例	变量、函数和文件的命名	camelCase、snake_case、kebab-case、PascalCase
导入/导出	模块组织方式	Barrel 导出、相对路径与绝对路径、路径别名
错误处理	如何管理故障	try/catch、Result 类型、错误边界、自定义异常
测试模式	测试框架和风格	文件命名（*.test.ts 与 *.spec.ts）、结构（describe/it 与 test）
状态管理	数据流动方式	Redux、Zustand、Context、Vuex、Pinia、Livewire
API 模式	通信方式	REST、GraphQL、tRPC、RPC、WebSocket
数据库访问	数据层方案	ORM（Prisma、Eloquent、TypeORM）、原始 SQL、查询构建器
组件模式	UI 结构	原子设计、功能文件夹、样式共置

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

---

阶段 4：Git 历史分析

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

提取： 开发速度、提交消息惯例、分支策略、活跃区域。

停止：完成所有发现阶段后，再保存到记忆。

---

阶段 5：保存到记忆

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

memory/project-context.md

# 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]

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

## Key Dependencies
[Critical libraries and their roles]

memory/learned-patterns.md

# 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]

memory/user-preferences.md

# User Preferences



## Communication Style
[Terse? Detailed? Prefers code over explanation?]

## Workflow Preferences
[PR workflow? Branch naming? Commit style?]

## Review Preferences
[What they focus on in reviews?]

memory/decisions-log.md

# Decisions Log


## YYYY-MM-DD: [Decision Title]
**Decision:** [What was decided]
**Context:** [Why this came up]
**Rationale:** [Why this was chosen over alternatives]
**Alternatives considered:** [What else was considered]

---

阶段 6：更正协议

当用户纠正某项假设时：

1. 立即确认这项更正——不要为错误的假设辩解
2. 确定需要更新哪个记忆文件
3. 更新记忆文件，写入更正内容、日期和上下文
4. 立即应用这项更正，调整当前工作
5. 传播——检查这项更正是否会使记忆中的其他假设失效

更正类型	要更新的记忆文件	示例
命名约定错误	learned-patterns.md	“我们使用 snake_case，而不是 camelCase”
技术栈错误	project-context.md	“我们使用 Vitest，而不是 Jest”
工作流偏好	user-preferences.md	“始终创建 PR，不要推送到 main”
架构理解有误	project-context.md	“那是微服务，不是单体应用”
决策背景	decisions-log.md	“我们选择 X 是因为 Y，而不是 Z”

不要跳过记忆更新。未持久化的更正会被重复犯错。

---

阶段 7：会话开始——记忆验证

当记忆文件已存在时：

1. 加载 memory/ 目录中的所有记忆文件
2. 检查 Last updated 日期——标记所有超过 30 天的条目
3. 抽查 2-3 项事实，并与当前代码库核对（例如，package.json 是否仍列有相同的框架？）
4. 如果发现不一致，针对发生变化的部分进行重新扫描
5. 用当前信息更新过时条目

---

决策表：探索深度

情况	探索深度	时间预算
全新项目，没有记忆文件	完整（所有阶段）	3-5 分钟
已知项目中的新区域	定向（仅针对该区域执行阶段 2-3）	1-2 分钟
用户更正	仅执行更正协议（阶段 6）	30 秒
会话开始时已有记忆	仅验证（阶段 7）	1 分钟
检测到重大重构（许多文件已更改）	完整重新扫描	3-5 分钟

---

反模式／常见错误

不要做什么	失败原因	应该怎么做
阅读项目中的每个文件	浪费上下文窗口，速度慢	有策略地扫描：先看配置文件，再看 3-5 个有代表性的代码文件
根据一个文件推断约定	单个文件可能是例外	持久化之前，先在 2 个或更多文件中验证这些模式
完全覆盖记忆文件	丢失历史背景和用户更正	追加内容或更新特定章节，保留历史记录
跳过 git 历史	错过开发速度和团队模式	始终检查近期提交和贡献者
将猜测作为事实持久化	以错误背景污染未来会话	仅持久化有证据支持的观察结果
忽视用户更正	重复犯同样的错误	更正应立即覆盖观察结果
深入研究实现细节	只见树木，不见森林	关注模式和约定，而不是具体逻辑
会话开始时跳过记忆验证	使用过时的上下文	始终将记忆与当前代码库进行抽查核对

---

防止自我合理化

想法	事实
“我已经了解这个框架”	你并不了解这个项目的约定。去扫描。
“这些记忆文件还够新”	仍要抽查。代码变化很快。
“这项更正无关紧要”	小更正可以避免大错误。要持久化。
“不写下来我也会记得”	你不会记得。各个会话彼此独立。要将其持久化到记忆中。
“扫描会花太长时间”	不扫描会导致错误假设，之后修正起来更费时。

不要跳过记忆持久化。发现了什么，就写下来。

---

集成点

技能	关系
using-toolkit	在会话开始时触发自我学习
brainstorming	在生成想法前加载项目上下文
planning	利用已学习的模式提出一致的方案
code-review	根据已学习的约定检查代码
auto-improvement	记录发现效果指标
resilient-execution	失败模式会影响后续方案的选择

---

具体示例

发现命令序列

# 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

更正后的记忆更新

## 2026-03-15: Naming Convention Correction
**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

---

核心原则

• 观察，不要假设——基于代码库中的证据进行学习
• 增量更新——追加到记忆文件，不要覆盖
• 持久化前先验证——用至少 2 个示例再次核实观察结果
• 尊重更正——用户的更正会立即覆盖观察结果
• 保持最新——发生重大变化时重新扫描

---

技能类型

严格型——必须按顺序完成发现阶段。必须持久化记忆。必须立即记录更正。不要跳过阶段，也不要找理由回避扫描。