claude-memory

<core_principle> 记忆文件会占用上下文窗口中的令牌。自定义配置约有 100–150 个指令槽位。请保持文件精简——只写入 Agent 无法自行发现的信息。

两种方式：

• CLAUDE.md — 单个文件，适用于小型项目（< 100 行）
• .claude/rules/ — 模块化文件，支持按路径限定规则，适用于大型项目 </core_principle>

<quick_start> 运行 /init 自动生成 CLAUDE.md。也可以手动创建：

# Project Name

## Tech Stack
- [Primary framework]
- [Key non-obvious libraries]

## Commands
- `npm run dev` - Dev server
- `npm test` - Run tests
- `npm run build` - Build

## Rules
- [2-3 critical project-specific rules]

• 在会话中按 #，即可快速添加记忆条目
• 使用 /memory 在编辑器中打开 CLAUDE.md </quick_start>

<file_hierarchy>

优先级	位置	范围
1（最高）	企业策略（由 IT 管理）	所有组织用户
2	./CLAUDE.md 或 ./.claude/CLAUDE.md	通过 git 面向团队
2	./.claude/rules/*.md	通过 git 面向团队
3	~/.claude/CLAUDE.md	你的所有项目
3	~/.claude/rules/*.md	你的所有项目
4（最低）	./CLAUDE.local.md（自动加入 git 忽略）	仅你自己

Claude 会从当前目录向上递归，加载找到的所有 CLAUDE.md 文件。读取子目录中的文件时，也会发现该目录树中的 CLAUDE.md 文件。

Monorepo 策略： 根目录文件定义何时执行；子树文件定义如何执行。

root/CLAUDE.md           # Universal: tech stack, git workflow
apps/web/CLAUDE.md       # Frontend-specific
apps/api/CLAUDE.md       # Backend-specific

</file_hierarchy>

<rules_directory> .claude/rules/ 目录将指令拆分为重点明确的 Markdown 文件。

适合使用 .claude/rules/ 的情况： 涉及许多方面、不同文件类型有不同规则、团队成员维护不同区域。 适合使用 CLAUDE.md 的情况： 项目较小、规则通用、需要单一事实来源。

按路径限定的规则使用 YAML frontmatter：

---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation

支持的模式：**/*.ts、src/**/*、src/**/*.{ts,tsx}、{src,lib}/**/*.ts

没有 paths frontmatter 的规则会无条件加载。

完整指南请参阅 references/rules-directory-guide.md，其中包括符号链接、用户级规则和迁移。 </rules_directory>

<content_structure> CLAUDE.md 只需包含以下章节：

1. 项目用途（1–3 行）——项目是什么
2. 技术栈（精简）——仅列出不明显的技术
3. 命令——不明显的开发、构建和测试命令
4. 重要文件——仅列出架构关键且不明显的文件
5. 规则——防止错误的禁止事项和约束（价值最高的内容）
6. 工作流（可选）——仅在工作流不常规时添加

请勿包含：

• 仓库概览（Agent 会自行发现项目结构）
• 代码风格规则（代码检查工具会强制执行）
• 通用最佳实践（如“编写整洁代码”、“DRY”、“SOLID”）
• 冗余规范（配置文件副本、环境变量、架构描述）
• 营销内容/目标（愿景声明、KPI、路线图）
• 冗长说明（一行就能说明的内容不必写成段落）

可直接使用的模板请参阅 references/section-templates.md。 特定于框架的模式请参阅 references/project-patterns.md。 </content_structure>

<writing_rules> 黄金法则： 如果一个完全不了解项目背景的人读了你的 CLAUDE.md 后感到困惑，Claude 也会如此。

具体明确，切勿含糊：

❌ "Format code properly" / "Write good tests" / "Follow best practices"
✅ "Run `pnpm lint` before committing" / "Tests in `__tests__/` using Vitest"

优先写禁止事项，而非正向指导：

❌ "Try to use TanStack Form for forms"
✅ "NEVER use native form/useState for forms — ALWAYS use TanStack Form"

展示胜于讲述： 格式很重要时，请给出具体示例（最多 3–5 行）。

强调层级： CRITICAL > NEVER > ALWAYS > IMPORTANT > YOU MUST

• 每个章节中，关键规则放在最前面
• 对不可妥协的规则使用粗体 + 关键词：**CRITICAL**: Never commit secrets

高级技巧请参阅 references/prompting-techniques.md。 </writing_rules>

<size_limits>

• 理想长度： < 100 行
• 最大长度： 超过 150 行后性能会下降
• 超过 200 行： 指令开始被忽略

超过限制时，请拆分为 .claude/rules/ 文件或链接到单独的文档：

- **API patterns**: See [docs/api-patterns.md](docs/api-patterns.md)
- **Testing guide**: See [docs/testing-guide.md](docs/testing-guide.md)

CLAUDE.md 支持导入：@docs/coding-standards.md（相对/绝对路径、~ 展开，最多深入 5 层，不会在代码块内求值）。 </size_limits>

**务必先询问：存储策略**

创建或更新记忆文件之前，使用 AskUserQuestion：

• 选项 1：单个 CLAUDE.md — 少于 100 行，简单项目，通用规则
• 选项 2：模块化 .claude/rules/ — 100 行以上，针对不同文件使用不同规则

创建新记忆：

1. 从 /init 或最小模板开始
2. 首先添加技术栈和命令
3. 仅在遇到阻碍时添加规则
4. 使用实际任务进行测试，并根据 Claude 的行为迭代

维护：

1. 每季度或项目发生重大变化时进行审查
2. 移除过时的说明
3. 添加需要反复解释的模式
4. 工作期间使用 # 快速添加内容

故障排除：

问题	解决方案
Claude 忽略说明	缩减文件大小，添加强调（CRITICAL、NEVER）
上下文溢出	使用 /clear，拆分到 .claude/rules/
说明冲突	合并说明，使用层级结构（根目录与子目录）
路径规则未生效	确认 glob 模式与目标文件匹配

<init_workflow>

/claude-memory init — 创建最小化 CLAUDE.md

当用户参数中包含 "init" 时，执行此工作流，生成仅包含必要部分的 CLAUDE.md。

第 1 步：检测项目上下文

读取 package.json（或等效文件：pyproject.toml、Cargo.toml、go.mod 等），以检测：

• 项目名称
• 技术栈（框架、语言）
• 可用脚本/命令（dev、build、test）

同时检查现有的代码检查配置（ESLint、Biome、Prettier、tsconfig）——不要包含它们已经强制执行的规则。

第 2 步：识别重要文件

扫描架构中不明显但关键的文件。查找：

• 身份验证配置文件
• 服务端操作封装、API 辅助工具
• 数据库架构文件
• 自定义中间件或共享工具
• 跳过标准框架文件（package.json、tsconfig、next.config 等）

第 3 步：生成 CLAUDE.md

仅创建包含以下部分的文件。每个部分都应简洁——整个文件应少于 50 行。

# [Project Name]
[One-line description of what this project is]

## Tech Stack
- [Only non-obvious technologies — skip deps detectable from config files]

## Commands
- `[dev command]` - Dev server
- `[build command]` - Build
- `[test command]` - Tests
- [Any non-obvious commands like db:push, seed, etc.]

## Important Files
- [Only files the agent wouldn't discover naturally]

## Rules
- [Leave empty with a comment: "Add project-specific rules as you encounter friction"]

第 4 步：展示并写入

向用户展示生成的文件。获得批准后，将其写入 ./CLAUDE.md。

规则：

• 绝不要包含目录结构、代码风格规则、通用最佳实践或营销文案
• 绝不要包含代码检查工具或 TypeScript 已强制执行的内容
• 目标：20-50 行。若超过此范围，说明包含内容过多
• Rules 部分应为空——随着错误发生，再逐步填充 </init_workflow>

<optimize_workflow>

/claude-memory optimize — 深度清理 CLAUDE.md

当用户参数中包含 "optimize" 时，执行此工作流。

重要——第 0 步为必需步骤。切勿跳过。未先阅读指南，切勿开始优化。

第 0 步：阅读优化指南（必须首先执行）

在进行任何其他操作之前，必须使用 Read 工具读取 {SKILL_PATH}/references/optimize-guide.md。 此文件包含研究数据（ETH Zurich 研究）、6 类冗余内容及具体示例、目标指标和优化前后示例。不阅读此文件，你会遗漏删除标准，导致优化质量不佳。

第 1 步：盘点

读取项目中的每个 CLAUDE.md、CLAUDE.local.md 和 .claude/rules/*.md。统计总行数。

第 2 步：读取代码检查配置

读取 ESLint/Biome/Prettier/TypeScript 配置。CLAUDE.md 中任何与强制执行规则重复的行 → 删除。

步骤 3：应用指南中的 6 类冗余内容

逐行询问：“Agent 能否通过阅读项目发现这一点，或者是否有 linter 强制执行这一点？”如果可以 → 删除。

删除所有符合以下类别的内容：

1. Linter 强制执行的规则（ESLint、Prettier、Biome、TypeScript strict）
2. 营销内容／目标／愿景（对代码没有价值）
3. Agent 可以自行发现的显而易见的信息（目录结构、框架默认设置、来自 package.json 的依赖项）
4. 冗长的解释（本可用 1 行说明的段落、教程、历史）
5. 冗余的规范（配置文件副本、架构描述、环境变量列表）
6. 通用最佳实践（“编写整洁的代码”、“DRY”、“SOLID”）

步骤 4：只保留必要内容

• 项目用途（1-3 行）
• 技术栈（精简，仅列不明显的内容）
• 核心命令（仅列不明显的内容）
• 测试命令
• 重要文件（仅列不明显的内容）
• 项目特定规则（禁止事项 + 限制条件）
• 工作流（仅限非标准工作流）

步骤 5：精简

• 段落 → 项目符号
• 3 行规则 → 1 行规则
• 删除所有填充词（“为了”、“需要注意的是”）
• 合并相关条目

步骤 6：展示差异

展示修改前／后的内容及行数。每项删除内容都注明所属的冗余类别。 让用户批准后再应用更改。

目标： 理想情况下少于 100 行，最多少于 150 行。 </optimize_workflow>

<reference_guides>

• 优化指南：references/optimize-guide.md — 基于研究的冗余内容检查清单、6 类删除类别及修改前／后示例
• 规则目录：references/rules-directory-guide.md — 完整的 .claude/rules/ 指南，涵盖路径范围限定、YAML 语法、符号链接和迁移
• 提示词技巧：references/prompting-techniques.md — 强调策略、清晰度技巧、约束模式
• 章节模板：references/section-templates.md — 各类章节的可复制粘贴模板
• 综合示例：references/comprehensive-example.md — 完整的生产级 SaaS CLAUDE.md
• 项目模式：references/project-patterns.md — Next.js、Express、Python、Monorepo 模式 </reference_guides>