learn

学习

自主分析项目代码库，以发现开发模式、约定和架构决策，然后在 .claude/rules/ 中生成项目规则文件，供 Claude Code 遵循。

概述

此技能在双 Agent 架构中充当协调器。它负责协调整体工作流：收集项目上下文、将深入分析委托给 learn-analyst 子 Agent、筛选和排序结果、向用户展示发现，并将获批的规则保存到 .claude/rules/。

职责分离可确保分析器使用聚焦的取证提示词开展工作，而协调器则负责与用户交互并保存文件。

何时使用

以下情况可使用此技能：

• 用户要求“从此项目中学习”或“了解项目约定”
• 用户希望根据现有代码库自动生成 .claude/rules/ 文件
• 用户要求“提取项目规则”或“发现模式”
• 用户希望 Claude Code 学习项目的编码规范
• 加入新项目后，希望将现有约定整理成规则
• 开始开发大型功能前，确保 Claude 遵循项目模式

触发短语：“从项目中学习”“提取规则”“分析约定”“发现模式”“生成项目规则”“学习代码库”“自动生成规则”

指令

阶段 1：评估项目上下文

委托分析器之前，先收集项目的高层级上下文：

1. 确认项目根目录：确认当前工作目录是项目根目录（包含 package.json、pom.xml、pyproject.toml、go.mod、.git/ 或类似标记）

2. 检查现有规则：扫描已有规则文件，了解已记录的内容：

# Check for existing rules
ls -la .claude/rules/ 2>/dev/null || echo "No .claude/rules/ directory found"
cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"
cat AGENTS.md 2>/dev/null || echo "No AGENTS.md found"
ls -la .cursorrules 2>/dev/null || echo "No .cursorrules found"

3. 评估项目规模：快速了解项目范围：

# Quick project overview
find . -maxdepth 1 -type f -name "*.json" -o -name "*.toml" -o -name "*.xml" -o -name "*.gradle*" -o -name "Makefile" -o -name "*.yaml" -o -name "*.yml" | head -20
find . -type f -name "*.ts" -o -name "*.js" -o -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.php" | wc -l

4. 告知用户：简要告知用户发现的内容，并说明即将开始分析：
   • “我发现这是一个包含 [N] 个源文件和 [M] 条现有规则的 [TypeScript/NestJS] 项目。现在开始深入分析……”

阶段 2：委托给分析子 Agent

调用 learn-analyst 子 Agent，对代码库进行深入分析。

使用 Task 工具将分析委托给 learn-analyst Agent：

• Agent：learn-analyst
• 提示词：“分析当前工作目录中的代码库。遵循完整流程：发现、模式提取、分类和优先级排序。以 JSON 报告的形式返回发现结果。”
• 模式：同步运行，以便直接接收 JSON 报告

分析器会返回一份包含分类后发现结果的结构化 JSON 报告。

阶段 3：审核和筛选结果

处理分析器的报告：

1. 解析分析器返回的 JSON 报告
2. 验证发现结果：确保每项发现都包含：
   • 清晰的标题
   • 至少来自 2 个文件的证据
   • 影响分数 ≥ 4（舍弃影响较低的发现）
   • 格式正确的 Markdown 内容
3. 与现有规则去重：将每项发现的标题和内容与现有 .claude/rules/ 文件进行比较。跳过与现有规则重复的发现。
4. 选出前 3 项：从剩余发现中按影响分数选出前 3 项。如果筛选后不足 3 项，则展示剩余内容。
5. 如果没有剩余发现：告知用户项目已经有完善的文档，或没有发现未记录的重要模式。

阶段 4：向用户展示

以清晰、结构化的格式向用户展示筛选后的发现：

I analyzed your codebase and found N patterns worth documenting as project rules:

1. **[RULE]** <Title> (Impact: X/10)
   <One-line explanation>

2. **[RULE]** <Title> (Impact: X/10)
   <One-line explanation>

3. **[RULE]** <Title> (Impact: X/10)
   <One-line explanation>

然后使用 AskUserQuestion 请求用户确认：

• 提供选项：“保存全部 N 条规则”“让我选择要保存的规则”“取消——不保存任何内容”
• 如果用户希望逐条选择，则逐条展示规则，并提供“保存／跳过”选项
• 绝不自动保存——始终要求用户明确批准

阶段 5：保存已批准的规则

对于每条已批准的规则：

1. 确保目录存在：

mkdir -p .claude/rules

2. 生成文件名：将发现项的 title 字段转换为 kebab-case：

   • 示例："API Response Envelope Convention" → api-response-envelope-convention.md
   • 避免使用 rule-1.md 或 learned-pattern.md 这类通用名称

3. 检查冲突：写入前，检查是否已存在同名文件：

   • 如果文件已存在，向用户展示差异，并询问是替换、合并还是跳过

4. 写入规则文件：使用分析人员预先格式化的内容，在 .claude/rules/ 中创建文件

5. 向用户确认：保存后，列出所有已创建的文件：

✅ Rules saved successfully:

  .claude/rules/api-response-envelope-convention.md
  .claude/rules/feature-based-module-organization.md
  .claude/rules/test-factory-pattern.md

These rules will be automatically applied by Claude Code in future sessions.

最佳实践

1. 尽早在项目中运行：加入新项目时使用此技能，快速整理出规范
2. 保存前先审查：务必确认生成的规则适用于你的项目
3. 持续迭代：随着项目演进定期运行此技能，可能会出现新的模式
4. 保存后编辑：生成的规则只是起点；应进一步完善，使其符合你的具体偏好
5. 将规则提交到 git：.claude/rules/ 文件针对具体项目，应纳入版本控制，让整个团队受益

限制与警告

关键限制

1. 未经确认不得保存：写入任何文件前，务必询问用户
2. 仅限项目本地：只能写入当前项目目录中的 .claude/rules/，不得写入全局路径
3. 只读分析：分析子 Agent 不得修改任何项目文件
4. 基于证据：每条规则都必须有代码库中的具体证据支持
5. 不得臆造：不得编造代码库中实际不存在的模式
6. 尊重现有规则：未经用户明确批准，不得覆盖现有规则
7. 保持规则聚焦：每个规则文件都应针对一种具体规范或模式

局限

• 大型单体代码库：分析大型代码库可能需要更长时间。分析人员会扫描有代表性的样本，而非每个文件。
• 多语言项目：在多语言项目中，规则会按语言生成。确保规则标题注明适用的语言范围。
• 与现有规则冲突：如果项目已有全面的 .claude/rules/，此技能可能只发现少量或没有新模式。这是预期情况。
• 动态模式：有些模式只会在运行时出现（例如，中间件的顺序）。此技能侧重于静态代码库分析。

示例

示例 1：从 NestJS 项目中学习

用户请求：“从这个项目中学习”

阶段 1 — 上下文评估：

Found: TypeScript/NestJS project with 142 source files
Existing rules: 0 files in .claude/rules/
Starting deep analysis...

阶段 4 — 呈现：

I analyzed your codebase and found 3 patterns worth documenting as project rules:

1. **[RULE]** Feature-Based Module Organization (Impact: 9/10)
   All modules follow src/modules/<feature>/ with controller, service, dto, entity subdirectories.

2. **[RULE]** DTO Validation Convention (Impact: 8/10)
   All DTOs use class-validator decorators and follow Create/Update naming pattern.

3. **[RULE]** Error Response Envelope (Impact: 7/10)
   All API errors return { statusCode, message, error } consistent envelope format.

Save all 3 rules? [Save all / Let me choose / Cancel]

阶段 5 — 持久化：

✅ Rules saved successfully:

  .claude/rules/feature-based-module-organization.md
  .claude/rules/dto-validation-convention.md
  .claude/rules/error-response-envelope.md

These rules will be automatically applied by Claude Code in future sessions.

示例 2：已有规则的项目

用户请求：“发现项目模式”

阶段 1 — 上下文评估：

Found: Java/Spring Boot project with 87 source files
Existing rules: 4 files in .claude/rules/
Starting deep analysis...

阶段 3 — 筛选后：

The analyst found 6 patterns, but 4 overlap with your existing rules.
After deduplication, 2 new patterns remain:

1. **[RULE]** Repository Method Naming (Impact: 7/10)
   All custom repository methods use findBy/existsBy/countBy prefix convention.

2. **[RULE]** Integration Test Database Strategy (Impact: 6/10)
   Integration tests use @Testcontainers with PostgreSQL and @Sql for fixtures.

Save these 2 rules? [Save all / Let me choose / Cancel]