Back to Details

project-memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Memory Skill

项目内存技能

Set up and organize Claude Code's project memory system for consistent, context-aware assistance.
设置并整理Claude Code的项目内存系统，以获得一致、具备上下文感知能力的协助。

Core Principle

核心原则

Project memory teaches Claude Code how to work with your specific codebase. Well-organized project memory leads to more accurate, consistent, and helpful responses.
项目内存用于教会Claude Code如何适配你的特定代码库。 组织有序的项目内存能让Claude Code给出更准确、一致且实用的响应。

Memory Hierarchy

内存层级

Claude Code reads instructions in this order (higher = more precedence):
  1. Enterprise policy (managed, highest)
  2. User memory (
    ~/.claude/CLAUDE.md
    )
  3. Project memory (
    CLAUDE.md
    in project root)
  4. Modular rules (
    .claude/rules/*.md
    )
  5. Local memory (
    CLAUDE.local.md
    , gitignored)
Later sources override earlier ones for conflicting instructions.
Claude Code会按以下顺序读取指令（优先级从高到低）：
  1. 企业策略（托管式，优先级最高）
  2. 用户内存（
    ~/.claude/CLAUDE.md
    ）
  3. 项目内存（项目根目录下的
    CLAUDE.md
    ）
  4. 模块化规则（
    .claude/rules/*.md
    ）
  5. 本地内存（
    CLAUDE.local.md
    ，已加入git忽略）
当指令存在冲突时，后续来源的内容会覆盖之前的。

File Types

文件类型

CLAUDE.md (Project Root)

CLAUDE.md（项目根目录）

Purpose: Primary project instructions, conventions, and context
Location: Project root directory
Visibility: Checked into git, shared with team
Contents:
  • Project overview and architecture
  • Development commands (build, test, lint)
  • Coding conventions and patterns
  • Important constraints or requirements
  • Links to key documentation
用途： 项目的主要指令、规范和上下文信息
位置： 项目根目录
可见性： 已提交至git，供团队共享
内容：
  • 项目概述与架构
  • 开发命令（构建、测试、代码检查）
  • 编码规范与模式
  • 重要约束或要求
  • 关键文档链接

.claude/rules/*.md

.claude/rules/*.md

Purpose: Modular, path-specific rules
Location: 
.claude/rules/
directory
Visibility: Checked into git
Features:
  • Automatically loaded based on file path
  • Supports subdirectories
  • Can use YAML frontmatter with 
    globs
    for path-specific targeting
用途： 模块化的、路径专属规则
位置： 
.claude/rules/
目录
可见性： 已提交至git
特性：
  • 根据文件路径自动加载
  • 支持子目录
  • 可使用带有
    globs
    的YAML前置元数据实现路径精准定位

CLAUDE.local.md

CLAUDE.local.md

Purpose: Personal, machine-specific instructions
Location: Project root directory
Visibility: Should be gitignored
Use cases:
  • Personal preferences
  • Local environment paths
  • Machine-specific configurations
  • Experimental instructions
用途： 个人专属、机器特定的指令
位置： 项目根目录
可见性： 应加入git忽略
使用场景：
  • 个人偏好设置
  • 本地环境路径
  • 机器特定配置
  • 实验性指令

Setting Up Project Memory

设置项目内存

1. Create CLAUDE.md

1. 创建CLAUDE.md

Start with essential project information:
markdown
undefined
从基础项目信息开始：
markdown
undefined

Project Name

项目名称

Brief description of what this project does.
项目功能的简要描述。

Development Commands

开发命令

Build

npm run build

# Test
npm test

# Lint
npm run lint

构建

npm run build

# 测试
npm test

# 代码检查
npm run lint

Architecture

架构

  • src/
    - Source code
  • tests/
    - Test files
  • docs/
    - Documentation
  • src/
    - 源代码
  • tests/
    - 测试文件
  • docs/
    - 文档

Conventions

规范

  • Use TypeScript for all new code
  • Follow existing patterns in the codebase
  • Run tests before committing
  • 所有新代码使用TypeScript
  • 遵循代码库中的现有模式
  • 提交前运行测试

Key Files

关键文件

  • src/index.ts
    - Main entry point
  • src/config.ts
    - Configuration handling
undefined
  • src/index.ts
    - 主入口文件
  • src/config.ts
    - 配置处理
undefined

2. Add Modular Rules (Optional)

2. 添加模块化规则（可选）

Create path-specific rules in 
.claude/rules/
:
text
.claude/
  rules/
    api.md          # Rules for API code
    tests.md        # Rules for test files
    components/
      forms.md      # Rules for form components
在
.claude/rules/
中创建路径专属规则：
text
.claude/
  rules/
    api.md          # API代码规则
    tests.md        # 测试文件规则
    components/
      forms.md      # 表单组件规则

3. Path-Specific Rules with Globs

3. 通配符路径专属规则

Use YAML frontmatter to target specific paths:
markdown
---
paths: ["src/api/**/*.ts", "src/services/**/*.ts"]
---
使用YAML前置元数据定位特定路径：
markdown
---
paths: ["src/api/**/*.ts", "src/services/**/*.ts"]
---

API Development Rules

API开发规则

  • All API functions must be async
  • Always validate input parameters
  • Use consistent error response format
  • Include JSDoc with @throws annotations
undefined
  • 所有API函数必须为异步
  • 始终验证输入参数
  • 使用一致的错误响应格式
  • 包含带有@throws注解的JSDoc
undefined

4. Import Syntax

4. 导入语法

Reference other files from CLAUDE.md:
markdown
undefined
在CLAUDE.md中引用其他文件：
markdown
undefined

Project Instructions

项目指令

See architecture: @docs/ARCHITECTURE.md See API guidelines: @docs/API_GUIDELINES.md

Imported files are treated as direct context.
查看架构：@docs/ARCHITECTURE.md 查看API指南：@docs/API_GUIDELINES.md

被导入的文件会被视为直接上下文的一部分。

CLAUDE.md Template

CLAUDE.md模板

markdown
undefined
markdown
undefined

[Project Name]

[项目名称]

[One-paragraph description of what this project does]
[项目功能的一段简要描述]

Quick Start

快速开始

Install dependencies

[command]

# Run development server
[command]

# Run tests
[command]

安装依赖

[命令]

# 启动开发服务器
[命令]

# 运行测试
[命令]

Architecture

架构

[Brief overview of project structure]
[项目结构的简要概述]

Key Directories

关键目录

  • src/
    - [Description]
  • tests/
    - [Description]
  • config/
    - [Description]
  • src/
    - [描述]
  • tests/
    - [描述]
  • config/
    - [描述]

Key Files

关键文件

  • src/index.ts
    - [Description]
  • src/config.ts
    - [Description]
  • src/index.ts
    - [描述]
  • src/config.ts
    - [描述]

Development Guidelines

开发指南

Code Style

代码风格

  • [Style convention 1]
  • [Style convention 2]
  • [风格规范1]
  • [风格规范2]

Testing

测试

  • [Testing convention 1]
  • [Testing convention 2]
  • [测试规范1]
  • [测试规范2]

Git Workflow

Git工作流

  • [Commit convention]
  • [Branch convention]
  • [提交规范]
  • [分支规范]

Common Tasks

常见任务

Adding a New Feature

添加新功能

  1. [Step 1]
  2. [Step 2]
  3. [Step 3]
  1. [步骤1]
  2. [步骤2]
  3. [步骤3]

Running Tests

运行测试

[test command]
[测试命令]

Important Notes

重要说明

  • [Critical constraint or requirement]
  • [Security consideration]
  • [Performance consideration]
undefined
  • [关键约束或要求]
  • [安全注意事项]
  • [性能注意事项]
undefined

Path-Specific Rules Examples

路径专属规则示例

For API Code

API代码规则

markdown
---
paths: ["src/api/**/*.ts"]
---
markdown
---
paths: ["src/api/**/*.ts"]
---

API Development Rules

API开发规则

Request Handling

请求处理

  • Validate all input with zod schemas
  • Return consistent error format: 
    { error: string, code: string }
  • Always set appropriate HTTP status codes
  • 使用zod schema验证所有输入
  • 返回一致的错误格式：
    { error: string, code: string }
  • 始终设置合适的HTTP状态码

Authentication

认证

  • All endpoints require auth unless in ALLOWED_PUBLIC_ROUTES
  • Use 
    requireAuth()
    middleware
  • 所有端点均需认证，除非在ALLOWED_PUBLIC_ROUTES中
  • 使用
    requireAuth()
    中间件

Response Format

响应格式

// Success { data: T, meta?: { page, total } }
// Error
{ error: string, code: string, details?: object }
undefined
// 成功 { data: T, meta?: { page, total } }
// 错误
{ error: string, code: string, details?: object }
undefined

For Test Files

测试文件规则

markdown
---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---
markdown
---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---

Testing Rules

测试规则

Structure

结构

  • Use 
    describe()
    for grouping related tests
  • Use 
    it()
    with descriptive names: "should [action] when [condition]"
  • One assertion per test when possible
  • 使用
    describe()
    分组相关测试
  • 使用
    it()
    并搭配描述性名称："should [操作] when [条件]"
  • 尽可能每个测试对应一个断言

Mocking

模拟

  • Prefer dependency injection over mocking
  • Mock at boundaries (API, database, file system)
  • Clear mocks between tests
  • 优先使用依赖注入而非模拟
  • 在边界处进行模拟（API、数据库、文件系统）
  • 测试间清空模拟数据

Coverage

覆盖率

  • All public functions need tests
  • Test happy path and error cases
  • Include edge cases
undefined
  • 所有公共函数都需要测试
  • 测试正常流程和错误场景
  • 包含边缘情况
undefined

For React Components

React组件规则

markdown
---
paths: ["src/components/**/*.tsx"]
---
markdown
---
paths: ["src/components/**/*.tsx"]
---

Component Rules

组件规则

Structure

结构

  • One component per file
  • Export component as default
  • Co-locate styles with component
  • 一个文件对应一个组件
  • 组件以默认导出方式导出
  • 样式与组件放在同一目录

Props

属性

  • Define props interface above component
  • Use destructuring in function signature
  • Document required vs optional props
  • 在组件上方定义props接口
  • 在函数签名中使用解构
  • 标注必填与可选props

State

状态

  • Prefer controlled components
  • Lift state up when shared between components
  • Use hooks for complex state logic
undefined
  • 优先使用受控组件
  • 当组件间共享状态时提升状态层级
  • 使用hooks处理复杂状态逻辑
undefined

Best Practices

最佳实践

Keep It Concise

保持简洁

Bad:
markdown
undefined
不良示例：
markdown
undefined

Introduction

简介

This project is a web application that allows users to manage their tasks. It was started in 2023 and has grown to include many features including task creation, task editing, task deletion, task filtering, task sorting, task searching, task sharing, and task exporting...

**Good:**

```markdown
Task management web app. Users create, edit, filter, and share tasks.
本项目是一个允许用户管理任务的Web应用。 始于2023年，现已包含众多功能，包括任务创建、任务编辑、任务删除、任务筛选、任务排序、任务搜索、任务分享和任务导出...

**良好示例：**

```markdown
任务管理Web应用。用户可创建、编辑、筛选和分享任务。

Be Specific and Actionable

具体且可执行

Bad:
markdown
Write good code and follow best practices.
Good:
markdown
- Use TypeScript strict mode
- Run `npm run lint` before committing
- All functions need JSDoc comments
不良示例：
markdown
编写优质代码并遵循最佳实践。
良好示例：
markdown
- 使用TypeScript严格模式
- 提交前运行`npm run lint`
- 所有函数需添加JSDoc注释

Include Commands

包含命令

Bad:
markdown
Build the project before deploying.
Good:
markdown
    npm run build
    npm run deploy
不良示例：
markdown
部署前构建项目。
良好示例：
markdown
    npm run build
    npm run deploy

Use Imports for Long Content

对长内容使用导入

Bad: Everything in one huge CLAUDE.md
Good:
markdown
undefined
不良示例： 所有内容都放在一个庞大的CLAUDE.md中
良好示例：
markdown
undefined

Project

项目

Quick overview here.
此处为快速概述。

Detailed Documentation

详细文档

Architecture: @docs/ARCHITECTURE.md API Guide: @docs/API.md Deployment: @docs/DEPLOYMENT.md
undefined
架构：@docs/ARCHITECTURE.md API指南：@docs/API.md 部署：@docs/DEPLOYMENT.md
undefined

Path-Specific Over Generic

优先路径专属规则而非通用规则

Bad:
markdown
undefined
不良示例：
markdown
undefined

CLAUDE.md

CLAUDE.md

When writing tests, always use Jest. When writing API code, always validate input. When writing components, always use TypeScript.

**Good:**
.claude/rules/tests.md -> Jest rules .claude/rules/api.md -> Validation rules .claude/rules/components.md -> TypeScript rules
undefined
编写测试时始终使用Jest。 编写API代码时始终验证输入。 编写组件时始终使用TypeScript。

**良好示例：**
.claude/rules/tests.md -> Jest规则 .claude/rules/api.md -> 验证规则 .claude/rules/components.md -> TypeScript规则
undefined

When to Update Project Memory

何时更新项目内存

Add New Instructions

添加新指令

  • Onboarding reveals missing context
  • Repeated questions indicate gaps
  • New conventions are established
  • Architecture changes significantly
  • 新员工入职时发现缺失上下文信息
  • 重复出现的问题表明存在信息缺口
  • 确立了新的规范
  • 架构发生重大变化

Review Existing Instructions

审查现有指令

  • Code changes make instructions outdated
  • Team feedback indicates confusion
  • Patterns evolve over time
  • 代码变更导致指令过时
  • 团队反馈表明存在困惑
  • 模式随时间演变

Common Patterns

常见模式

Monorepo Setup

单体仓库设置

markdown
undefined
markdown
undefined

Monorepo

单体仓库

Packages

包

  • packages/core/
    - Core library
  • packages/cli/
    - CLI tool
  • packages/web/
    - Web application
  • packages/core/
    - 核心库
  • packages/cli/
    - CLI工具
  • packages/web/
    - Web应用

Commands

命令

Build all packages

npm run build

# Test specific package
npm run test --workspace=packages/core

构建所有包

npm run build

# 测试特定包
npm run test --workspace=packages/core

Rules

规则

See package-specific rules in each package's 
.claude/rules/
directory.
undefined
查看每个包的
.claude/rules/
目录中的包专属规则。
undefined

Environment-Specific Notes

环境特定说明

Keep in 
CLAUDE.local.md
(gitignored):
markdown
undefined
将此类内容放在
CLAUDE.local.md
中（已加入git忽略）：
markdown
undefined

Local Setup Notes

本地设置说明

Environment

环境

  • Using Node 20.x
  • PostgreSQL running on port 5433 (not default)
  • Redis running in Docker
  • 使用Node 20.x
  • PostgreSQL运行在端口5433（非默认）
  • Redis在Docker中运行

Personal Preferences

个人偏好

  • Prefer verbose test output
  • Always run lint before suggesting changes
undefined
  • 偏好详细的测试输出
  • 建议修改前始终运行代码检查
undefined

Integration with Han Plugins

与Han插件的集成

Han plugins can contribute to project memory through hooks:
  • SessionStart hooks can inject plugin-specific context
  • UserPromptSubmit hooks can add reminders about conventions
  • Blueprints complement CLAUDE.md with detailed system documentation
Han插件可通过钩子为项目内存提供内容：
  • SessionStart钩子可注入插件专属上下文
  • UserPromptSubmit钩子可添加关于规范的提醒
  • Blueprints可补充CLAUDE.md，提供详细的系统文档

Troubleshooting

故障排除

Claude Code ignores instructions

Claude Code忽略指令

  1. Check file location (must be project root for CLAUDE.md)
  2. Check syntax (YAML frontmatter must be valid)
  3. Check glob patterns match the files you're editing
  4. More specific rules override general ones
  1. 检查文件位置（CLAUDE.md必须在项目根目录）
  2. 检查语法（YAML前置元数据必须有效）
  3. 检查通配符模式是否匹配你正在编辑的文件
  4. 更具体的规则会覆盖通用规则

Rules conflict between files

文件间规则冲突

  • Later in hierarchy wins
  • More specific globs win over general
  • Local overrides project
  • 层级靠后的规则优先
  • 更具体的通配符规则优先于通用规则
  • 本地规则覆盖项目规则

Performance with large CLAUDE.md

大型CLAUDE.md的性能问题

  • Use imports for detailed docs
  • Keep CLAUDE.md focused on essentials
  • Move detailed rules to 
    .claude/rules/
  • 对详细文档使用导入
  • 保持CLAUDE.md聚焦于核心内容
  • 将详细规则移至
    .claude/rules/

Remember

注意事项

  1. Start small - Basic commands and conventions first
  2. Be specific - Actionable instructions, not vague guidelines
  3. Stay current - Update when code changes
  4. Use hierarchy - Modular rules for path-specific needs
  5. Test it - Verify Claude Code follows your instructions
Good project memory makes Claude Code a better collaborator.
  1. 从小处着手 - 先设置基础命令和规范
  2. 具体明确 - 使用可执行的指令，而非模糊的指南
  3. 保持更新 - 代码变更时同步更新
  4. 利用层级 - 使用模块化规则处理路径专属需求
  5. 进行测试 - 验证Claude Code是否遵循你的指令
优质的项目内存能让Claude Code成为更出色的协作伙伴。