古法编程

Claude Code 的记忆系统通过 CLAUDE.md 文件实现持久化上下文管理，以支持跨会话协作。本文提供三个可直接使用的模板：项目级 project-CLAUDE.md 用于定义全团队共享的架构、标准与工作流；目录级 directory-api-CLAUDE.md 用于覆盖特定模块（如 API）的详细规范；个人级 personal-CLAUDE.md 用于设定开发者偏好的编码风格、工具链与调试习惯。这些模板清晰地展示了如何通过结构化的 Markdown 文件和 @import 语法来系统化管理 Claude Code 的记忆。

3 个 CLAUDE.md 模板：项目级、目录级和个人偏好配置

Claude Code 的记忆系统是其高级功能的基石，它允许开发者将项目规范、团队标准和个人偏好以 CLAUDE.md 文件的形式持久化。这些文件在每次会话启动时被自动加载，为 Claude 提供关键的上下文背景。与其从零开始编写，不如参考经过设计的模板。Claude HowTo 教程指南提供了三个层次分明的模板，分别对应团队协作、模块化管理和个人定制的需求。

1. 项目级模板：构建团队共识的基础

项目级的 CLAUDE.md（通常位于项目根目录的 ./CLAUDE.md 或 ./.claude/CLAUDE.md）是团队共享的“法律文件”。它通过 Git 进行版本控制，确保所有成员，包括 Claude，在同一套规则下工作。一个设计良好的项目级模板应涵盖项目全貌。

根据 project-CLAUDE.md 模板，其标准结构包含以下核心部分：

# Project Configuration

## Project Overview
- **Name**: E-commerce Platform
- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker
- **Team Size**: 5 developers
- **Deadline**: Q4 2025

## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md

## Development Standards

### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters
- Use 2-space indentation

### Naming Conventions
- **Files**: kebab-case (user-controller.js)
- **Classes**: PascalCase (UserService)
- **Functions/Variables**: camelCase (getUserById)
- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL)
- **Database Tables**: snake_case (user_accounts)

### Git Workflow
- Branch names: `feature/description` or `fix/description`
- Commit messages: Follow conventional commits
- PR required before merge
- All CI/CD checks must pass
- Minimum 1 approval required

### Testing Requirements
- Minimum 80% code coverage
- All critical paths must have tests
- Use Jest for unit tests
- Use Cypress for E2E tests
- Test filenames: `*.test.ts` or `*.spec.ts`

## Common Commands

| Command | Purpose |
|---------|---------|
| `npm run dev` | Start development server |
| `npm test` | Run test suite |
| `npm run lint` | Check code style |
| `npm run build` | Build for production |
| `npm run migrate` | Run database migrations |

## Team Contacts
- Tech Lead: Sarah Chen (@sarah.chen)
- Product Manager: Mike Johnson (@mike.j)
- DevOps: Alex Kim (@alex.k)

设计思路提炼：这个模板的核心在于全面性与可操作性。它不只是罗列规则，而是构建了一个完整的协作框架。

  1. 上下文导入：通过 @import 语法（如 @docs/architecture.md）将外部详细文档引入记忆，避免重复劳动并保持单一信息源。
  2. 可执行的规范：具体到文件命名规则（kebab-case）、测试覆盖率底线（80%）、Git 分支策略等，为 Claude 的编码和审查提供了明确的判断依据。
  3. 效率工具：将 npm run dev 等高频命令制成表格，Claude 可以快速理解并辅助执行项目日常任务。
  4. 人际关系图谱：记录团队联系人，有助于 Claude 理解协作上下文，在生成代码审查或文档时能考虑到相关的干系人。

这个模板确保了无论哪位开发者或哪个代码库实例启动 Claude，获得的都是关于“我们这个项目如何工作”的统一体验。

2. 目录级模板：精细控制特定模块规范

目录级的 CLAUDE.md（例如位于 ./src/api/CLAUDE.md）用于覆盖项目级模板中的通用规则，为特定模块或子目录定义专属标准。它体现了记忆系统的层级优先级，目录级文件的设置可以针对其作用范围覆盖项目级的设置。

以 directory-api-CLAUDE.md 模板为例，它专注于 API 模块的工程化标准：

# API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

## API-Specific Standards

### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors
- Include field-level error details

### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours
- Implement refresh token mechanism

### Response Format

All responses must follow this structure:
{
  "success": true,
  "data": { /* actual data */ },
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

### Pagination
- Use cursor-based pagination (not offset)
- Include `hasMore` boolean
- Limit max page size to 100
- Default page size: 20

### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints
- Return 429 when exceeded
- Include `retry-after` header

### Caching
- Use Redis for session caching
- Cache duration: 5 minutes default
- Invalidate on write operations
- Tag cache keys with resource type

设计思路提炼：这个模板的价值在于深度与一致性。它不再讨论宏观的项目框架，而是深入到技术决策的细枝末节。

  1. 强制性规范：明确了工具选型（Zod 用于验证）、交互契约（统一的响应 JSON 结构）和策略（JWT 认证、缓存失效机制），直接指导 Claude 生成符合高标准的代码。
  2. 防御性编程：强调了输入验证、错误处理（400 状态码与详细错误）、限流（429 状态码与 retry-after 头）和缓存管理，这些是构建健壮 API 的关键，Claude 会遵循这些原则来编写代码或审查现有代码。
  3. 性能与可扩展性考量：规定使用游标分页而非偏移分页，这直接影响大数据量下的 API 性能。通过配置缓存策略，Claude 在生成或优化相关代码时会自动考虑缓存层。

这种目录级配置使得当 Claude 处理 src/api/ 目录下的任何文件时，其行为都会被精确地约束在该模块的规范之内，实现了高度专业化。

3. 个人偏好模板：个性化你的 AI 助手

个人级的 CLAUDE.md（位于 ~/.claude/CLAUDE.md）是所有项目共享的个人偏好设置。它不属于任何特定项目，而是跟随开发者本人，影响其在所有项目中与 Claude 的协作体验。

personal-CLAUDE.md 模板展示了如何配置个人工作风格：

# My Development Preferences

## About Me
- **Experience Level**: 8 years full-stack development
- **Preferred Languages**: TypeScript, Python
- **Communication Style**: Direct, with examples
- **Learning Style**: Visual diagrams with code

## Code Preferences

### Error Handling
I prefer explicit error handling with try-catch blocks and meaningful error messages.
Avoid generic errors. Always log errors for debugging.

### Comments
Use comments for WHY, not WHAT. Code should be self-documenting.
Comments should explain business logic or non-obvious decisions.

### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.
Focus on behavior, not implementation details.

## Debugging Preferences
- Use console.log with prefix: `[DEBUG]`
- Include context: function name, relevant variables
- Use stack traces when available
- Always include timestamps in logs

## Communication
- Explain complex concepts with diagrams
- Show concrete examples before explaining theory
- Include before/after code snippets
- Summarize key points at the end

## Tooling
- **IDE**: VS Code with vim keybindings
- **Terminal**: Zsh with Oh-My-Zsh
- **Format**: Prettier (100 char line length)
- **Linter**: ESLint with airbnb config
- **Test Framework**: Jest with React Testing Library

设计思路提炼：这个模板的核心是塑造人机交互的默契。

  1. 风格化指导：它明确了你偏好的错误处理风格（显式 try-catch）、注释哲学（解释“为什么”而不是“是什么”）以及测试驱动开发（TDD）流程。Claude 会依据这些偏好来生成更符合你习惯的代码。
  2. 沟通协议：定义了你希望 Claude 如何解释复杂问题——“用图表说明”、“先给具体例子”。这直接优化了你获取信息和理解方案的效率。
  3. 工具链映射：列出了你日常使用的编辑器、终端、格式化工具和测试框架。Claude 可以基于此推荐或生成与你的工具链兼容的脚本、配置或命令。

个人偏好模板将 Claude 从一个通用的助手转变为了解你工作习惯的“同事”，显著提升了协作的流畅度和产出的匹配度。

核心技巧：使用 @import 引用外部文档

这三个模板都体现了 Claude Code 记忆系统的一个强大特性：@import 语法。它允许在 CLAUDE.md 中引用外部文件，将它们的内容整合到上下文中。

## Architecture
@docs/architecture.md
@docs/api-standards.md
@~/.claude/shared-guidelines.md

关键点：

  • 支持相对与绝对路径：@docs/api.md 引用项目内文档，@~/.claude/my-docs.md 可以引用用户目录下的共享文档。
  • 避免重复与分叉：保持文档的单一信源。更新 docs/architecture.md 后，所有引用它的 CLAUDE.md 都会自动获得最新内容。
  • 递归与深度限制：支持最多 5 层递归导入，足以应对大多数文档组织需求。
  • 安全审批：首次导入来自项目外部的文件时，Claude Code 会提示用户确认，保障安全性。

灵活运用 @import，可以将庞大的项目规范、外部参考文档甚至个人共享指南编织进 Claude 的记忆网络，实现知识的高效集成。

FAQ

Q: 如果项目级和目录级的 CLAUDE.md 规则冲突，Claude 听谁的？ A: Claude Code 的记忆系统遵循明确的优先级顺序。目录级（如 ./src/api/CLAUDE.md）的设置会覆盖项目级（./CLAUDE.md）中针对相同配置项的设置。对于 API 模块，Claude 会优先采用 src/api/CLAUDE.md 中的规范。

Q: @import 语法可以用来引用代码文件或二进制文件吗？ A: 不可以。@import 语法设计用于引用文本格式的 Markdown 文档，以便将其内容作为上下文提供给 Claude。它不支持直接导入代码文件（如 .js, .py）或二进制文件。如需让 Claude 关注特定代码，更好的做法是在 CLAUDE.md 中通过描述或路径引用进行说明。