高效编写 CLAUDE.md 文件

使用 Claude Code 进行软件开发

Dani Zysman

AI Curriculum Manager @ DataCamp

CLAUDE.md 最佳实践

  • 先用 /init,再迭代
    • 当 Claude 出错时补充上下文
    • 记录规范变更
  • 目标:随项目演进的活文档
使用 Claude Code 进行软件开发

当前项目结构

music-analytics-api/
  app.py           # Application entry point
  routes.py        # API endpoints
  models.py        # Artist/Album models
  analytics.py     # Statistics functions
  middleware.py    # Request logging
  config.py        # Session settings
  CLAUDE.md        # <- Project memory file
使用 Claude Code 进行软件开发

CLAUDE.md 的取舍:IN vs. OUT

recraft: CLAUDE.md 中该写与不该写

规则:超过便签条长度的内容就不该放。

使用 Claude Code 进行软件开发

迭代维护 CLAUDE.md

> Add error handling to the /artists endpoint.
Done. I've added error handling to /artists (routes.py:9-19):
- Try-except block wrapping retrieval and serialization
- AttributeError handler if the data store isn't initialized
- General exception handler returning error details with 500 status

return jsonify({'error': f'Failed to retrieve artists: {str(e)}'}), 500
> Don't expose exception details to users, that's a security risk. Log internally 
and return a generic message.  Update CLAUDE.md.
Updated /artists to log errors internally and return a 
generic 500 message. CLAUDE.md updated with the convention: 
never expose exception details in responses.
使用 Claude Code 进行软件开发

好与糟的 CLAUDE.md 对比

臃肿(200+ 行)

# Inventory API
This is an Inventory Management 
API built with Flask...

## Full Source Code
### routes.py
from flask import jsonify...
[entire file pasted]

### models.py
[entire file pasted]

## API Documentation
GET /items returns...

良好(15 行)

# Inventory API
Flask REST API for inventory.

## Commands
- Run: flask run --port 5001
- Test: pytest tests/

## Conventions
- Use type hints
- Keep routes thin
使用 Claude Code 进行软件开发

文件引用 - 使用 @

> @routes.py what endpoints does this API have?
API Endpoints (6 GET routes)

Artists
- GET /artists              All artists
- GET /artists/<id>         Single artist by ID
- GET /artists/<id>/albums  Albums for an artist
Albums
- GET /albums               All albums
- GET /stats/albums         Album popularity statistics
- GET /stats/average-tracks Average track count per album

All endpoints return JSON.
使用 Claude Code 进行软件开发

CLAUDE.md + @ 的配合

# CLAUDE.md - Music Analytics API
A Flask-based REST API for music data analytics, providing endpoints for artists,
albums, and statistics.
...

## Key Files @routes.py - API endpoint definition @models.py - Artist and Album data models with in-memory store ...

CLAUDE.md 提供持久上下文。结合使用 @,让 Claude 始终知道关键文件。

使用 Claude Code 进行软件开发

三层上下文

CLAUDE.md 上下文的三层级

使用 Claude Code 进行软件开发

各自适用场景

  • CLAUDE.md(项目,公用)

    • 测试命令、编码约定、项目结构
  • CLAUDE.local.md(项目,个人)

    • 本地路径、API 密钥、个人流程偏好
  • ~/.claude/CLAUDE.md(全局,个人)

    • 跨项目的风格偏好
    • 您始终期望的默认行为
使用 Claude Code 进行软件开发

第 1 章回顾

  • /init 与 CLAUDE.md → 持久项目上下文
  • Shift+Tab 或 /plan → 切换 Plan 模式
  • think ... ultrathink → 深度推理(5 个层级)
使用 Claude Code 进行软件开发

让我们一起练习吧!

使用 Claude Code 进行软件开发

Preparing Video For Download...