learn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learn

学习

Autonomously analyzes a project's codebase to discover development patterns, conventions, and architectural decisions, then generates project rule files in

.claude/rules/

for Claude Code to follow.

自动分析项目代码库，发现开发模式、规范和架构决策，随后生成.claude/rules/目录下的项目规则文件供Claude Code遵循。

Overview

概述

This skill acts as the Orchestrator in a two-agent architecture. It coordinates the overall workflow: gathering project context, delegating deep analysis to the

learn-analyst

sub-agent, filtering and ranking results, presenting findings to the user, and persisting approved rules to

.claude/rules/

The separation of concerns ensures the analyst operates with a focused forensic prompt while the orchestrator manages user interaction and file persistence.

该技能在双Agent架构中充当**Orchestrator（编排器）**角色。它协调整体工作流程：收集项目上下文、将深度分析任务委派给

learn-analyst

子Agent、过滤并排序结果、向用户展示发现结果，以及将经批准的规则持久化到.claude/rules/目录中。

关注点分离确保分析Agent在专注的取证提示下运行，而编排器则管理用户交互和文件持久化。

When to Use

使用场景

Use this skill when:

User asks to "learn from this project" or "understand project conventions"
User wants to auto-generate
```
.claude/rules/
```
files from the existing codebase
User asks to "extract project rules" or "discover patterns"
User wants Claude Code to learn the project's coding standards
After joining a new project and wanting to codify existing conventions
Before starting a large feature to ensure Claude follows project patterns

Trigger phrases: "learn from project", "extract rules", "analyze conventions", "discover patterns", "generate project rules", "learn codebase", "auto-generate rules"

在以下场景中使用该技能：

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

触发短语："learn from project"、"extract rules"、"analyze conventions"、"discover patterns"、"generate project rules"、"learn codebase"、"auto-generate rules"

Instructions

操作步骤

Phase 1: Project Context Assessment

阶段1：项目上下文评估

Before delegating to the analyst, gather high-level project context:

Verify project root: Confirm the current working directory is a project root (has
```
package.json
```
,
```
pom.xml
```
,
```
pyproject.toml
```
,
```
go.mod
```
,
```
.git/
```
, or similar markers)
Check existing rules: Scan for pre-existing rule files to understand what is already documented:

bash

undefined

在委派给分析Agent之前，先收集项目的高层上下文：

验证项目根目录：确认当前工作目录是项目根目录（包含
```
package.json
```
、
```
pom.xml
```
、
```
pyproject.toml
```
、
```
go.mod
```
、
```
.git/
```
或类似标识）
检查现有规则：扫描是否存在预先编写的规则文件，了解已有的文档内容：

bash

undefined

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. **Assess project size**: Get a quick overview of the project scope:

```bash


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

```bash

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. **Inform the user**: Briefly tell the user what you found and that you are about to start analysis:
   - "I found a [TypeScript/NestJS] project with [N] source files and [M] existing rules. Starting deep analysis..."


4. **告知用户**：简要向用户说明你的发现，并告知即将开始分析：
   - "我发现了一个[TypeScript/NestJS]项目，包含[N]个源文件和[M]条现有规则。开始深度分析..."

Phase 2: Delegate to Analyst Sub-Agent

阶段2：委派给分析子Agent

Invoke the

learn-analyst

sub-agent to perform the deep codebase analysis.

Use the Task tool to delegate analysis to the

learn-analyst

agent:

Agent:
```
learn-analyst
```
Prompt: "Analyze the codebase in the current working directory. Follow your full process: discovery, pattern extraction, classification, and prioritization. Return your findings as a JSON report."
Mode: Run synchronously to receive the JSON report directly

The analyst will return a structured JSON report with classified findings.

调用

learn-analyst

子Agent执行深度代码库分析。

使用Task工具将分析任务委派给

learn-analyst

Agent：

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

分析Agent将返回包含分类发现结果的结构化JSON报告。

Phase 3: Review and Filter Results

阶段3：审核并过滤结果

Process the analyst's report:

Parse the JSON report returned by the analyst
Validate findings: Ensure each finding has:
- A clear title
- Evidence from at least 2 files
- Impact score ≥ 4 (discard low-impact findings)
- Well-formed markdown content
Deduplicate against existing rules: Compare each finding title and content against existing
```
.claude/rules/
```
files. Skip findings that duplicate existing rules.
Select top 3: From the remaining findings, select the top 3 by impact score. If fewer than 3 remain after filtering, present whatever is left.
If zero findings remain: Inform the user that the project is already well-documented or no significant undocumented patterns were found.

处理分析Agent的报告：

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

Phase 4: Present to User

阶段4：向用户展示结果

Present the filtered findings to the user in a clear, structured format:

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>

Then ask the user for confirmation using AskUserQuestion:

Present choices: "Save all N rules", "Let me choose which ones to save", "Cancel — don't save anything"
If the user wants to select individually, present each rule one by one with "Save / Skip" options
Never save automatically — always require explicit user approval

以清晰、结构化的格式向用户展示过滤后的发现结果：

我分析了你的代码库，发现N个值得作为项目规则记录的模式：

1. **[规则]** <标题>（影响评分：X/10）
   <一行说明>

2. **[规则]** <标题>（影响评分：X/10）
   <一行说明>

3. **[规则]** <标题>（影响评分：X/10）
   <一行说明>

然后使用AskUserQuestion询问用户确认：

提供选项："保存全部N条规则"、"让我选择要保存的规则"、"取消——不保存任何内容"
如果用户希望单独选择，则逐个展示每条规则，并提供"保存/跳过"选项
绝不自动保存——始终需要用户明确批准

Phase 5: Persist Approved Rules

阶段5：持久化已批准的规则

For each approved rule:

Ensure directory exists:

bash

mkdir -p .claude/rules

Generate the file name: Use the finding's
```
title
```
field converted to kebab-case:
- Example:
```
"API Response Envelope Convention"
```
  →
```
api-response-envelope-convention.md
```
- Avoid generic names like
```
rule-1.md
```
  or
```
learned-pattern.md
```
Check for conflicts: Before writing, check if a file with the same name already exists:
- If it exists, present a diff to the user and ask whether to replace, merge, or skip
Write the rule file: Create the file in
```
.claude/rules/
```
with the analyst's pre-formatted content
Confirm to user: After saving, list all created files:

✅ 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.

对于每条已批准的规则：

bash

mkdir -p .claude/rules

生成文件名：将发现结果的
```
title
```
字段转换为短横线分隔格式（kebab-case）：
- 示例：
```
"API Response Envelope Convention"
```
  →
```
api-response-envelope-convention.md
```
- 避免使用
```
rule-1.md
```
  或
```
learned-pattern.md
```
  这类通用名称
检查冲突：写入前，检查是否已存在同名文件：
- 如果已存在，向用户展示差异，并询问是否替换、合并或跳过
写入规则文件：在.claude/rules/目录下创建文件，内容使用分析Agent预先格式化好的内容
向用户确认：保存完成后，列出所有创建的文件：

✅ 规则保存成功：

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

这些规则将在未来的会话中由Claude Code自动应用。

Best Practices

最佳实践

Run early in a project: Use this skill when joining a new project to quickly codify conventions
Review before saving: Always verify the generated rules make sense for your project
Iterate: Run the skill periodically as the project evolves — new patterns may emerge
Edit after saving: Generated rules are starting points; refine them to match your exact preferences
Commit rules to git:
```
.claude/rules/
```
files are project-specific and should be version-controlled so the whole team benefits

在项目早期运行：加入新项目时使用该技能，快速将规范整理成文档
保存前审核：始终验证生成的规则是否符合项目需求
迭代运行：定期运行该技能，随着项目发展可能会出现新的模式
保存后编辑：生成的规则是起点，可根据实际偏好进行细化
将规则提交到Git：.claude/rules/文件是项目专属的，应进行版本控制，让整个团队受益

Constraints and Warnings

约束与警告

Critical Constraints

关键约束

Never save without confirmation: Always ask the user before writing any files
Project-local only: Only write to
```
.claude/rules/
```
in the current project directory, never to global paths
Read-only analysis: The analyst sub-agent must not modify any project files
Evidence-based: Every rule must be backed by concrete evidence from the codebase
No hallucination: Do not invent patterns that are not actually present in the codebase
Respect existing rules: Do not overwrite existing rules without explicit user approval
Keep rules focused: Each rule file should address one specific convention or pattern

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

Limitations

局限性

Large monorepos: Analysis may take longer on very large codebases. The analyst scans representative samples, not every file.
Polyglot projects: In multi-language projects, rules are generated per-language. Ensure the rule title indicates the language scope.
Existing rules conflict: If the project already has comprehensive
```
.claude/rules/
```
, the skill may find few or no new patterns. This is expected.
Dynamic patterns: Some patterns only emerge at runtime (e.g., middleware ordering). This skill focuses on static codebase analysis.

大型单体仓库：在非常大的代码库上分析可能需要更长时间。分析Agent会扫描代表性样本，而非每个文件。
多语言项目：在多语言项目中，规则是按语言生成的。确保规则标题明确语言范围。
现有规则冲突：如果项目已有全面的.claude/rules/规则，该技能可能很少或无法发现新模式，这是正常现象。
动态模式：有些模式仅在运行时出现（如中间件顺序）。该技能专注于静态代码库分析。

Examples

示例

Example 1: Learning from a NestJS project

示例1：从NestJS项目学习

User request: "Learn from this project"

Phase 1 — Context assessment:

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

Phase 4 — Presentation:

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]

Phase 5 — Persistence:

✅ 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.

用户请求："Learn from this project"

阶段1——上下文评估：

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

阶段4——展示结果：

我分析了你的代码库，发现3个值得作为项目规则记录的模式：

1. **[规则]** 基于功能的模块组织（影响评分：9/10）
   所有模块遵循src/modules/<功能>/的结构，包含controller、service、dto、entity子目录。

2. **[规则]** DTO验证规范（影响评分：8/10）
   所有DTO使用class-validator装饰器，并遵循Create/Update命名模式。

3. **[规则]** 错误响应信封格式（影响评分：7/10）
   所有API错误返回格式一致的{ statusCode, message, error }信封结构。

是否保存全部3条规则？[保存全部 / 让我选择 / 取消]

阶段5——持久化：

✅ 规则保存成功：

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

这些规则将在未来的会话中由Claude Code自动应用。

Example 2: Project with existing rules

示例2：已有规则的项目

User request: "Discover project patterns"

Phase 1 — Context assessment:

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

Phase 3 — After filtering:

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]

用户请求："Discover project patterns"

阶段1——上下文评估：

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

阶段3——过滤后：

分析Agent发现了6个模式，但其中4个与现有规则重复。
去重后，剩余2个新模式：

1. **[规则]** 仓库方法命名规范（影响评分：7/10）
   所有自定义仓库方法使用findBy/existsBy/countBy前缀规范。

2. **[规则]** 集成测试数据库策略（影响评分：6/10）
   集成测试使用@Testcontainers搭配PostgreSQL，并使用@Sql加载测试数据。

是否保存这2条规则？[保存全部 / 让我选择 / 取消]