/si:promote — 将学习经验提升为规则 (Graduate Learnings to Rules)

将已验证的模式从 Claude 的自动记忆移动到项目的规则系统中，使其成为强制执行的指令，而不仅仅是背景记录。

用法 (Usage)

/si:promote <模式描述>                    # 自动检测最佳目标 (Auto-detect best target)
/si:promote <模式> --target claude.md             # 提升到 CLAUDE.md (Promote to CLAUDE.md)
/si:promote <模式> --target rules/testing.md      # 提升到限定范围的规则 (Promote to scoped rule)
/si:promote <模式> --target rules/api.md --paths "src/api/**/*.ts"  # 带路径范围 (Scoped with paths)

工作流 (Workflow)

步骤 1：理解模式 (Step 1: Understand the pattern)

解析用户的描述。如果描述模糊，询问一个澄清性问题：

• “Claude 应该遵循什么具体行为？”
• “这适用于所有文件还是特定路径？”

步骤 2：在自动记忆中查找模式 (Step 2: Find the pattern in auto-memory)

# 在 MEMORY.md 中搜索相关条目 (Search MEMORY.md for related entries)
MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
grep -ni "<关键词>" "$MEMORY_DIR/MEMORY.md"

显示匹配的条目并确认这些是用户所指的。

步骤 3：确定合适的目标 (Step 3: Determine the right target)

如果用户未指定目标，根据范围推荐一个。

步骤 4：提炼为简洁的规则 (Step 4: Distill into a concise rule)

将自动记忆中的描述性记录转换为 CLAUDE.md 的指令格式：

之前 (Before)（MEMORY.md — 描述性）：

项目使用 pnpm 工作区。当我尝试 npm install 时失败了。锁文件是 pnpm-lock.yaml。必须使用 pnpm install 来安装依赖。

之后 (After)（CLAUDE.md — 规范性）：

## 构建与依赖 (Build & Dependencies)
- 包管理器 (Package manager): pnpm (不是 npm - not npm)。使用 `pnpm install`。

提炼规则 (Rules for distillation):

• 尽可能每行一条规则
• 使用祈使语气（“使用 X”、“始终 Y”、“从不 Z”）
• 包含命令或示例，而不仅仅是概念
• 没有背景故事——只有指令

步骤 5：写入目标文件 (Step 5: Write to target)

对于 CLAUDE.md:

1. 读取现有的 CLAUDE.md
2. 找到合适的章节（或创建一个）
3. 在正确的标题下追加新规则
4. 如果文件将超过 200 行，建议改用 .claude/rules/

对于 .claude/rules/:

1. 如果文件不存在，则创建它
2. 如果具有范围，添加带有 paths 的 YAML frontmatter
3. 写入规则内容

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*"
---

# API 开发规则 (API Development Rules)

- 所有端点必须使用 Zod 模式验证输入 (All endpoints must validate input with Zod schemas)
- 使用 `ApiError` 类处理错误响应（不要使用原始 Error）(Use `ApiError` class for error responses - not raw Error)
- 在处理函数上包含 OpenAPI JSDoc 注释 (Include OpenAPI JSDoc comments on handler functions)

步骤 6：清理自动记忆 (Step 6: Clean up auto-memory)

提升后，删除或标记 MEMORY.md 中的原始条目：

# 显示将要删除的内容 (Show what will be removed)
grep -n "<模式>" "$MEMORY_DIR/MEMORY.md"

请用户确认删除。然后编辑 MEMORY.md 以删除已提升的条目。这为新学习腾出了空间。

步骤 7：确认 (Step 7: Confirm)

✅ 已提升到 {{目标}} (Promoted to {{target}})

规则 (Rule): "{{提炼后的规则 (distilled rule)}}"
来源 (Source): MEMORY.md 第 {{n}} 行（已删除）(line {{n}} - removed)
MEMORY.md: {{行数}}/200 行剩余 ({{lines}}/200 lines remaining)

该模式现在是一条强制执行指令。Claude 将在所有未来的会话中遵循它。
(The pattern is now an enforced instruction. Claude will follow it in all future sessions.)

提升决策指南 (Promotion Decision Guide)

应该提升的情况 (Promote when):

• 模式在自动记忆中出现 3 次以上
• 你为此纠正了 Claude 不止一次
• 这是任何贡献者都应该知道的项目约定
• 它可以防止重复发生的错误

不应该提升的情况 (Don’t promote when):

• 这是一次性的调试记录（留在自动记忆中）
• 它是会话特定的上下文（会话记忆处理此情况）
• 它可能很快会改变（例如，在迁移期间）
• 它已经被现有规则覆盖

CLAUDE.md 与 .claude/rules/ 的选择 (CLAUDE.md vs .claude/rules/)

提示 (Tips)

• 保持 CLAUDE.md 少于 200 行——超出部分使用 rules/ 目录
• 每行一条规则比段落更易于维护
• 包含具体的命令，而不仅仅是概念
• 每季度审查已提升的规则——删除不再相关的部分