improve-claude-md

当用户提供 CLAUDE.md 文件（或要求你改进该文件）时，请按照以下原则和结构重写。

核心问题

Claude Code 会为每个 CLAUDE.md 注入一条系统提醒：

“此上下文可能与当前任务相关，也可能无关。除非此上下文与当前任务高度相关，否则不要回应此上下文。”

这意味着 Claude 会忽略它认为无关的 CLAUDE.md 内容。与当前任务无关的内容越多，Claude 越有可能忽略所有内容，包括重要内容。

解决方案：<important if="condition"> 区块

使用 <important if="condition"> XML 标签包裹 CLAUDE.md 中仅在特定条件下相关的部分。这样可以利用 Claude Code 自身系统提示词使用的 XML 标签模式，为模型提供明确的相关性信号，避免“可能相关，也可能无关”的表述造成影响。

原则

1. 基础上下文不加标签，领域指南使用标签包裹

并非所有内容都应放入 <important if> 区块。几乎所有任务都会用到的上下文——项目身份、项目结构、技术栈——应以普通 Markdown 形式放在文件顶部。这些是 Agent 始终需要了解的入门信息。

仅在特定任务中有用的领域专属指南——测试模式、API 约定、状态管理、i18n——应使用 <important if> 区块包裹，并设置有针对性的条件。

经验法则：如果某条内容与 90% 以上的任务相关，就不要加标签。如果它只与某一类工作相关，就用标签包裹。

2. 条件必须具体且有针对性

不好的示例——过于宽泛、几乎适用于所有情况的条件：

<important if="you are writing or modifying any code">
- Use absolute imports
- Use functional components
- Use camelCase filenames
</important>

好的示例——每条规则都有各自明确且具体的触发条件：

<important if="you are adding or modifying imports">
- Use `@/` absolute imports (see tsconfig.json for path aliases)
- Avoid default exports except in route files
</important>

<important if="you are creating new components">
- Use functional components with explicit prop interfaces
</important>

<important if="you are creating new files or directories">
- Use camelCase for file and directory names
</important>

3. 保持简洁，谨慎使用渐进式披露

不要拆分成多个文件并要求 Agent 调用工具来查找，除非额外上下文极其冗长或复杂。

<important if> 区块的核心作用是将所有内容放在文件中，同时根据条件调整其权重——Agent 可以看到所有内容，但只会关注与当前任务相符的部分。

尽量保持文件简洁。

4. 越少越好

• 前沿模型能够可靠地遵循数百条指令。Claude Code 的系统提示词和工具已经占用了约 50 条。CLAUDE.md 应尽可能精简。
• 删除任何可由代码检查工具、格式化工具或提交前钩子强制执行的指令。
• 删除任何可从现有代码模式中发现的指令。大模型能够通过上下文学习——如果代码库始终使用某种模式，Agent 搜索几次后就会遵循该模式。
• 删除代码片段。它们会过时，也会让文件变得臃肿。改用文件路径引用（例如“参见 src/utils/example.ts 中的模式”）。

5. 保留所有命令

不要删除原文件中的命令。命令表是基础参考资料——即使某些命令使用频率较低，Agent 也需要知道有哪些命令可用。

输出结构

重写 CLAUDE.md 时，请采用以下结构：

# CLAUDE.md

[one-line project identity — what it is, what it's built with]

## Project map
[directory listing with brief descriptions]

<important if="you need to run commands to build, test, lint, or generate code">
[commands table — all commands from the original]
</important>

<important if="<specific trigger for rule 1>">
[rule 1]
</important>

<important if="<specific trigger for rule 2>">
[rule 2]
</important>

... more rules, each with their own block ...

<important if="<specific trigger for domain area 1>">

[guidance]

</important>

... more domain sections ...

如何应用

收到现有的 CLAUDE.md 并需要改进时：

1. 识别项目身份 — 提取一个句子来描述项目是什么。将其作为顶部的独立内容。
2. 提取目录结构图 — 将其作为独立内容保留（不使用 <important if> 包装）。这是基础上下文。
3. 提取技术栈 — 如果有，将其作为顶部附近的独立内容保留。精简为一到两行。
4. 提取命令 — 保留原文中的所有命令。用一个 <important if> 块包装。
5. 拆分规则 — 将规则列表拆分为多个带有具体条件的 <important if> 块。可以将规则分组，但绝不能将无关规则归在同一个宽泛条件下。
6. 包装领域章节 — 测试、API 模式、状态管理、i18n 等内容各自使用一个块，并注明该知识适用的条件。
7. 删除 Linter 范畴的内容 — 删除风格指南、格式规则以及任何可由工具强制执行的内容。建议改用推送前或提交前钩子。
8. 删除代码片段 — 替换为文件路径引用。
9. 删除模糊指令 — 删除诸如“利用 X Agent”或“遵循最佳实践”这类不具体且不可执行的内容。

示例

输入：

# CLAUDE.md

This is an Express API with a React frontend in a Turborepo monorepo.

## Commands

| Command | Description |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
| `turbo storybook` | Start Storybook |
| `turbo db:generate` | Generate Prisma client |
| `turbo db:migrate` | Run database migrations |
| `turbo analyze` | Bundle analyzer |

## Project Structure

- `apps/api/` - Express REST API
- `apps/web/` - React SPA
- `packages/db/` - Prisma schema and client
- `packages/ui/` - Shared component library
- `packages/config/` - Shared configuration

## Coding Standards

- Use named exports
- Use functional components with TypeScript interfaces for props
- Use camelCase for variables, PascalCase for components
- Prefer `const` over `let`
- Always use strict equality (`===`)
- Use template literals instead of string concatenation
- Write JSDoc comments for all public functions
- Use barrel exports in index.ts files

## API Development

- All routes go in `apps/api/src/routes/`
- Use Zod for request validation
- Use Prisma for database access
- Error responses follow RFC 7807 format
- Authentication via JWT middleware

## Testing

- Jest + Supertest for API tests
- Vitest + Testing Library for frontend
- Test fixtures in `__fixtures__/` directories
- Use `createTestClient()` helper for API integration tests
- Mock database with `prismaMock` from `packages/db/test`

## State Management

- Zustand for global client state
- React Query for server state
- URL state via `nuqs`

输出：

# CLAUDE.md

Express API + React frontend in a Turborepo monorepo.

## Project map

- `apps/api/` - Express REST API
- `apps/web/` - React SPA
- `packages/db/` - Prisma schema and client
- `packages/ui/` - Shared component library
- `packages/config/` - Shared configuration

<important if="you need to run commands to build, test, lint, or generate code">

Run with `turbo` from the repo root.

| Command | What it does |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
| `turbo storybook` | Start Storybook |
| `turbo db:generate` | Regenerate Prisma client after schema changes |
| `turbo db:migrate` | Run database migrations |
| `turbo analyze` | Bundle analyzer |
</important>

<important if="you are adding or modifying imports or exports">
- Use named exports (no default exports)
</important>

<important if="you are creating new components">
- Use functional components with TypeScript interfaces for props
</important>

<important if="you are adding or modifying API routes">

- All routes go in `apps/api/src/routes/`
- Use Zod for request validation
- Use Prisma for database access
- Error responses follow RFC 7807 format
- Authentication via JWT middleware
</important>

<important if="you are writing or modifying tests">

- API: Jest + Supertest
- Frontend: Vitest + Testing Library
- Test fixtures in `__fixtures__/` directories
- Use `createTestClient()` helper for API integration tests
- Mock database with `prismaMock` from `packages/db/test`
</important>

<important if="you are working with state management, stores, or URL parameters">

- Zustand for global client state
- React Query for server state
- URL state via `nuqs`
</important>

删除了哪些内容及原因：

• camelCase/PascalCase、const 与 let、严格相等、模板字面量、JSDoc、barrel exports — 这些属于 Linter 和格式化工具的范畴，或可从现有代码模式中了解
• “编码规范”作为一个分组章节 — 按触发条件拆分为针对性的块

未删除哪些内容：

• 保留所有命令（包括 dev、storybook、analyze）
• 将项目结构图作为独立内容保留（基础信息，与每项任务都相关）