# Claude Code Python全栈实战：FastAPI项目从零到部署
## 概述
本教程面向零基础开发者，手把手教你用 Claude Code 从空白目录开始，构建一个完整的 Python FastAPI RESTful API 项目。你将学会安装配置 Claude Code、编写项目级 CLAUDE.md、用自然语言驱动开发、管理上下文与权限、运行测试并完成部署准备。学完后，你将具备用 Claude Code 独立交付 Python 后端项目的能力。
**适用人群**：有基础 Python 知识但未使用过 Claude Code 的开发者、想提升编码效率的后端工程师、技术团队负责人。
## 前置条件
| 条件 | 说明 |
|------|------|
| Python 3.11+ | 推荐使用 pyenv 或 conda 管理 |
| Node.js 18+ | Claude Code 运行所需 |
| Git 2.30+ | 版本控制 |
| Anthropic API Key | 在 [console.anthropic.com](https://console.anthropic.com) 获取 |
| 终端环境 | macOS / Linux / WSL2 均可 |
---
## 第一步：安装 Claude Code
### 1.1 全局安装
打开终端，执行一条命令完成安装：
```bash
npm install -g @anthropic-ai/claude-code
```
安装完成后验证版本：
```bash
claude --version
# 预期输出：claude 1.x.x (或更高版本)
```
> **常见问题**：如果遇到权限错误（EACCES），不要使用 `sudo`。推荐用 nvm 管理 Node.js，或执行：
> ```bash
> mkdir -p ~/.npm-global
> npm config set prefix '~/.npm-global'
> export PATH=~/.npm-global/bin:$PATH
> ```
### 1.2 认证方式
Claude Code 支持三种认证方式：
```mermaid
flowchart LR
A[认证方式选择] --> B[OAuth浏览器登录]
A --> C[API Key环境变量]
A --> D[API Key直接输入]
B --> B1[运行 claude 自动弹出]
C --> C1[export ANTHROPIC_API_KEY=sk-ant-xxx]
D --> D1[首次运行时粘贴]
style A fill:#7c3aed,color:#fff
style B fill:#10b981,color:#fff
style C fill:#10b981,color:#fff
style D fill:#10b981,color:#fff
```
**推荐方式 — OAuth 浏览器登录**（最安全，无需手动管理 Key）：
```bash
claude
# 浏览器自动打开，登录 Anthropic 账户即可
```
**备选方式 — API Key 环境变量**（适合 CI/CD 或远程服务器）：
```bash
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
claude
```
> **安全提示**：永远不要将 API Key 硬编码在代码或 CLAUDE.md 中。使用 `.env` 文件并加入 `.gitignore`。
### 1.3 验证安装
```bash
# 查看帮助信息
claude --help
# 查看配置位置
claude config list
```
---
## 第二步：项目初始化
### 2.1 创建项目目录
```bash
mkdir taskflow-api && cd taskflow-api
git init
```
### 2.2 使用 /init 初始化 Claude Code 配置
在项目目录中启动 Claude Code：
```bash
claude
```
进入交互界面后，输入：
```
/init
```
`/init` 命令会扫描项目结构，自动生成一个 `CLAUDE.md` 文件。由于这是一个空项目，它会创建一个基础模板。
### 2.3 编写项目级 CLAUDE.md
CLAUDE.md 是 Claude Code 理解你项目的"大脑"——它定义了项目规则、技术栈、代码风格和约定。这是我们教程中最关键的配置文件。
```markdown
# TaskFlow API
## 项目概述
任务管理 RESTful API，基于 Python FastAPI + SQLite 开发。
## 技术栈
- Python 3.11+
- FastAPI + Uvicorn
- SQLAlchemy 2.0 (async)
- SQLite (开发) / PostgreSQL (生产)
- Pytest + httpx (测试)
## 代码规范
- 使用 type hints，所有函数必须有参数和返回类型注解
- 遵循 PEP 8，单行最大 88 字符（Black 格式化）
- API 路由按资源分文件：routers/tasks.py, routers/users.py
- Pydantic v2 模型放在 schemas/ 目录
- 数据库模型放在 models/ 目录
## 项目结构
```
taskflow-api/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI 入口
│ ├── database.py # 数据库连接
│ ├── models/ # SQLAlchemy 模型
│ ├── schemas/ # Pydantic 模型
│ ├── routers/ # API 路由
│ └── crud/ # 数据库操作
├── tests/
├── CLAUDE.md
├── pyproject.toml
└── requirements.txt
```
## 常用命令
- 运行服务：`uvicorn app.main:app --reload`
- 运行测试：`pytest -v`
- 格式化：`black . && isort .`
- 类型检查：`mypy app/`
## 禁止事项
- 不要修改 .env 文件
- 不要运行 drop table 或删除数据库操作
- 测试使用 SQLite 内存数据库，不要依赖外部服务
```
将上述内容保存为 `CLAUDE.md`，放在项目根目录。
> **为什么 CLAUDE.md 如此重要？**
>
> 每次会话启动时，Claude Code 自动读取 CLAUDE.md 作为系统提示的一部分。它决定了 Claude 生成代码的风格、结构和边界。一份好的 CLAUDE.md 能将"能用"的输出提升到"生产级"。
### 2.4 创建 .gitignore
```
__pycache__/
*.pyc
.env
*.db
.venv/
.pytest_cache/
.mypy_cache/
.claude/
```
---
## 第三步：用 Claude Code 驱动开发
### 3.1 理解 Claude Code 的交互模式
```mermaid
flowchart TB
subgraph 交互模式
IM[交互模式] --> PM[Plan模式]
IM --> NM[正常模式]
IM --> AM[Agent模式]
end
PM --> PM1["输入前先规划
/plan 切换"]
NM --> NM1["边聊边写代码
默认模式"]
AM --> AM1["自动执行多步任务
/goal 切换"]
subgraph 核心操作
S1["Shift+Tab 切换模式"]
S2["Tab 自动补全"]
S3["Esc 取消当前操作"]
S4["Ctrl+C 中断生成"]
end
style IM fill:#7c3aed,color:#fff
style PM fill:#3b82f6,color:#fff
style NM fill:#10b981,color:#fff
style AM fill:#f59e0b,color:#fff
```
### 3.2 创建项目骨架
启动 Claude Code，输入第一条开发指令：
```
请按照 CLAUDE.md 中定义的项目结构，初始化这个 FastAPI 项目。
包括：pyproject.toml、app/main.py、app/database.py、空的 __init__.py 文件。
使用 SQLAlchemy 2.0 async 模式 + aiosqlite。
```
Claude Code 会：
1. 创建目录结构
2. 生成 `pyproject.toml` 依赖配置
3. 编写 `app/main.py` 入口文件
4. 配置 `app/database.py` 异步数据库连接
**预期生成的 `app/main.py`**：
```python
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(
title="TaskFlow API",
version="0.1.0",
description="任务管理 RESTful API",
)
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/health")
async def health_check() -> dict[str, str]:
return {"status": "ok"}
```
**预期生成的 `app/database.py`**：
```python
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase
DATABASE_URL = "sqlite+aiosqlite:///./taskflow.db"
engine = create_async_engine(DATABASE_URL, echo=False)
async_session = async_sessionmaker(engine, expire_on_commit=False)
class Base(DeclarativeBase):
pass
async def get_db() -> AsyncSession:
async with async_session() as session:
yield session
```
### 3.3 安装依赖
告诉 Claude Code：
```
安装项目依赖并创建虚拟环境
```
Claude Code 会执行：
```bash
python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn sqlalchemy aiosqlite pydantic
```
或者如果你用 Poetry：
```
用 Poetry 初始化项目，添加 fastapi, uvicorn, sqlalchemy, aiosqlite 依赖
```
### 3.4 定义数据模型
```
创建 Task 数据模型和对应的 Pydantic schema。
Task 需要字段：id, title, description, status (pending/in_progress/done),
priority (low/medium/high), created_at, updated_at。
使用 SQLAlchemy 2.0 声明式模型和 Pydantic v2。
```
Claude Code 会生成 `app/models/task.py`：
```python
import enum
from datetime import datetime
from sqlalchemy import DateTime, Enum, String, Text, func
from sqlalchemy.orm import Mapped, mapped_column
from app.database import Base
class TaskStatus(str, enum.Enum):
pending = "pending"
in_progress = "in_progress"
done = "done"
class TaskPriority(str, enum.Enum):
low = "low"
medium = "medium"
high = "high"
class Task(Base):
__tablename__ = "tasks"
id: Mapped[int] = mapped_column(primary_key=True)
title: Mapped[str] = mapped_column(String(200))
description: Mapped[str | None] = mapped_column(Text, default=None)
status: Mapped[TaskStatus] = mapped_column(
Enum(TaskStatus), default=TaskStatus.pending
)
priority: Mapped[TaskPriority] = mapped_column(
Enum(TaskPriority), default=TaskPriority.medium
)
created_at: Mapped[datetime] = mapped_column(
DateTime, server_default=func.now()
)
updated_at: Mapped[datetime] = mapped_column(
DateTime, server_default=func.now(), onupdate=func.now()
)
```
以及 `app/schemas/task.py`：
```python
from datetime import datetime
from pydantic import BaseModel, Field
from app.models.task import TaskPriority, TaskStatus
class TaskCreate(BaseModel):
title: str = Field(..., max_length=200)
description: str | None = None
status: TaskStatus = TaskStatus.pending
priority: TaskPriority = TaskPriority.medium
class TaskUpdate(BaseModel):
title: str | None = Field(None, max_length=200)
description: str | None = None
status: TaskStatus | None = None
priority: TaskPriority | None = None
class TaskResponse(BaseModel):
id: int
title: str
description: str | None
status: TaskStatus
priority: TaskPriority
created_at: datetime
updated_at: datetime
model_config = {"from_attributes": True}
```
### 3.5 实现 CRUD 操作
```
在 app/crud/task.py 中实现 Task 的完整 CRUD 操作。
使用 async/await，所有数据库操作都要用 async session。
包含：create_task, get_task, get_tasks (支持分页和状态过滤),
update_task, delete_task。
```
Claude Code 生成的 `app/crud/task.py`：
```python
from sqlalchemy import select, func
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.task import Task, TaskStatus
from app.schemas.task import TaskCreate, TaskUpdate
async def create_task(db: AsyncSession, task_data: TaskCreate) -> Task:
task = Task(**task_data.model_dump())
db.add(task)
await db.commit()
await db.refresh(task)
return task
async def get_task(db: AsyncSession, task_id: int) -> Task | None:
return await db.get(Task, task_id)
async def get_tasks(
db: AsyncSession,
status: TaskStatus | None = None,
skip: int = 0,
limit: int = 20,
) -> tuple[list[Task], int]:
query = select(Task)
count_query = select(func.count()).select_from(Task)
if status:
query = query.where(Task.status == status)
count_query = count_query.where(Task.status == status)
total = (await db.execute(count_query)).scalar_one()
result = await db.execute(
query.order_by(Task.created_at.desc()).offset(skip).limit(limit)
)
return list(result.scalars().all()), total
async def update_task(
db: AsyncSession, task_id: int, task_data: TaskUpdate
) -> Task | None:
task = await get_task(db, task_id)
if not task:
return None
for key, value in task_data.model_dump(exclude_unset=True).items():
setattr(task, key, value)
await db.commit()
await db.refresh(task)
return task
async def delete_task(db: AsyncSession, task_id: int) -> bool:
task = await get_task(db, task_id)
if not task:
return False
await db.delete(task)
await db.commit()
return True
```
### 3.6 创建 API 路由
```
创建 app/routers/tasks.py，实现完整的 RESTful API 路由。
使用 APIRouter，包含以下端点：
- POST /tasks — 创建任务
- GET /tasks — 列表（支持 ?status=pending&skip=0&limit=20）
- GET /tasks/{id} — 获取单个
- PUT /tasks/{id} — 更新
- DELETE /tasks/{id} — 删除
```
生成 `app/routers/tasks.py`：
```python
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from app.crud import task as crud
from app.database import get_db
from app.models.task import TaskStatus
from app.schemas.task import TaskCreate, TaskResponse, TaskUpdate
router = APIRouter(prefix="/tasks", tags=["tasks"])
@router.post("/", response_model=TaskResponse, status_code=201)
async def create_task(
task_data: TaskCreate, db: AsyncSession = Depends(get_db)
) -> TaskResponse:
task = await crud.create_task(db, task_data)
return task
@router.get("/", response_model=list[TaskResponse])
async def list_tasks(
status: TaskStatus | None = None,
skip: int = Query(0, ge=0),
limit: int = Query(20, ge=1, le=100),
db: AsyncSession = Depends(get_db),
) -> list[TaskResponse]:
tasks, _ = await crud.get_tasks(db, status=status, skip=skip, limit=limit)
return tasks
@router.get("/{task_id}", response_model=TaskResponse)
async def get_task(task_id: int, db: AsyncSession = Depends(get_db)) -> TaskResponse:
task = await crud.get_task(db, task_id)
if not task:
raise HTTPException(status_code=404, detail="Task not found")
return task
@router.put("/{task_id}", response_model=TaskResponse)
async def update_task(
task_id: int,
task_data: TaskUpdate,
db: AsyncSession = Depends(get_db),
) -> TaskResponse:
task = await crud.update_task(db, task_id, task_data)
if not task:
raise HTTPException(status_code=404, detail="Task not found")
return task
@router.delete("/{task_id}", status_code=204)
async def delete_task(
task_id: int, db: AsyncSession = Depends(get_db)
) -> None:
deleted = await crud.delete_task(db, task_id)
if not deleted:
raise HTTPException(status_code=404, detail="Task not found")
```
别忘了在 `app/main.py` 中注册路由：
```python
from app.routers import tasks
app.include_router(tasks.router)
```
### 3.7 添加数据库初始化
在 `app/main.py` 中添加启动事件：
```python
from contextlib import asynccontextmanager
from app.database import Base, engine
@asynccontextmanager
async def lifespan(app):
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
app = FastAPI(
title="TaskFlow API",
version="0.1.0",
lifespan=lifespan,
)
```
---
## 第四步：运行与测试
### 4.1 首次启动
告诉 Claude Code：
```
启动 FastAPI 服务，确认能正常运行
```
Claude Code 执行：
```bash
uvicorn app.main:app --reload
```
预期输出：
```
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process
INFO: Started server process
INFO: Waiting for application startup.
INFO: Application startup complete.
```
打开浏览器访问 `http://127.0.0.1:8000/docs`，可以看到 FastAPI 自动生成的 Swagger UI 文档。
### 4.2 快速验证 API
在另一个终端窗口测试：
```bash
# 创建任务
curl -X POST http://127.0.0.1:8000/tasks/ \
-H "Content-Type: application/json" \
-d '{"title": "学习 Claude Code", "priority": "high"}'
# 获取任务列表
curl http://127.0.0.1:8000/tasks/
# 健康检查
curl http://127.0.0.1:8000/health
```
### 4.3 编写测试
告诉 Claude Code：
```
在 tests/ 目录下创建完整的测试文件 test_tasks.py。
使用 pytest + httpx 的 AsyncClient，SQLite 内存数据库。
覆盖所有 CRUD 操作的 happy path 和 error case。
```
生成的 `tests/test_tasks.py`：
```python
import pytest
import pytest_asyncio
from httpx import ASGITransport, AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from app.database import Base, get_db
from app.main import app
TEST_DB_URL = "sqlite+aiosqlite://"
test_engine = create_async_engine(TEST_DB_URL, echo=False)
TestSession = async_sessionmaker(test_engine, expire_on_commit=False)
async def override_get_db() -> AsyncSession:
async with TestSession() as session:
yield session
app.dependency_overrides[get_db] = override_get_db
@pytest_asyncio.fixture(autouse=True)
async def setup_db():
async with test_engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
async with test_engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
@pytest.fixture
def base_url() -> str:
return "http://test"
@pytest.mark.asyncio
async def test_create_task(base_url: str) -> None:
async with AsyncClient(
transport=ASGITransport(app=app), base_url=base_url
) as client:
response = await client.post(
"/tasks/",
json={"title": "Test task", "priority": "high"},
)
assert response.status_code == 201
data = response.json()
assert data["title"] == "Test task"
assert data["status"] == "pending"
@pytest.mark.asyncio
async def test_list_tasks(base_url: str) -> None:
async with AsyncClient(
transport=ASGITransport(app=app), base_url=base_url
) as client:
await client.post("/tasks/", json={"title": "Task 1"})
await client.post("/tasks/", json={"title": "Task 2"})
response = await client.get("/tasks/")
assert response.status_code == 200
assert len(response.json()) == 2
@pytest.mark.asyncio
async def test_get_task_not_found(base_url: str) -> None:
async with AsyncClient(
transport=ASGITransport(app=app), base_url=base_url
) as client:
response = await client.get("/tasks/999")
assert response.status_code == 404
@pytest.mark.asyncio
async def test_update_task(base_url: str) -> None:
async with AsyncClient(
transport=ASGITransport(app=app), base_url=base_url
) as client:
create_resp = await client.post(
"/tasks/", json={"title": "Original"}
)
task_id = create_resp.json()["id"]
response = await client.put(
f"/tasks/{task_id}",
json={"title": "Updated", "status": "in_progress"},
)
assert response.status_code == 200
assert response.json()["title"] == "Updated"
@pytest.mark.asyncio
async def test_delete_task(base_url: str) -> None:
async with AsyncClient(
transport=ASGITransport(app=app), base_url=base_url
) as client:
create_resp = await client.post(
"/tasks/", json={"title": "To delete"}
)
task_id = create_resp.json()["id"]
response = await client.delete(f"/tasks/{task_id}")
assert response.status_code == 204
```
运行测试：
```bash
pip install pytest pytest-asyncio httpx
pytest -v
```
预期输出：
```
tests/test_tasks.py::test_create_task PASSED
tests/test_tasks.py::test_list_tasks PASSED
tests/test_tasks.py::test_get_task_not_found PASSED
tests/test_tasks.py::test_update_task PASSED
tests/test_tasks.py::test_delete_task PASSED
```
---
## 第五步：权限管理与安全配置
### 5.1 理解权限系统
Claude Code 的权限系统是三层模型：
```mermaid
flowchart TB
subgraph 权限层级
L1["全局设置
~/.claude/settings.json"]
L2["项目设置
.claude/settings.json"]
L3["会话设置
/permissions 命令"]
end
L1 --> |"继承"| L2
L2 --> |"覆盖"| L3
subgraph 规则类型
R1["allow — 自动允许"]
R2["deny — 永远禁止"]
R3["ask — 每次询问"]
end
L3 --> R1
L3 --> R2
L3 --> R3
style L1 fill:#7c3aed,color:#fff
style L2 fill:#3b82f6,color:#fff
style L3 fill:#10b981,color:#fff
```
### 5.2 配置项目权限
创建 `.claude/settings.json`：
```json
{
"permissions": {
"allow": [
"Bash(python *)",
"Bash(pytest *)",
"Bash(uvicorn *)",
"Bash(pip install *)",
"Bash(black *)",
"Bash(mypy *)",
"Read",
"Write",
"Edit"
],
"deny": [
"Bash(rm -rf *)",
"Bash(drop *)",
"Bash(DROP *)"
]
}
}
```
这样配置后：
- Claude Code 可以自由运行 Python、pytest、pip 等开发命令
- 读取、写入、编辑文件不受限制
- 但禁止执行删除和数据库 drop 操作
> **提示**：你也可以在会话中使用 `/permissions` 命令动态调整权限。
---
## 第六步：上下文管理技巧
### 6.1 核心概念
Claude Code 每次对话都消耗 token。随着会话变长，历史消息会占用越来越多的上下文窗口。管理好上下文是高效使用的关键。
```mermaid
flowchart LR
subgraph 上下文生命周期
S[新会话] --> G[增长阶段]
G --> C[compact压缩]
C --> G2[继续增长]
G2 --> C2[再次压缩]
C2 --> E[会话结束]
end
subgraph 管理命令
CMD1["/compact — 压缩历史"]
CMD2["/clear — 清空会话"]
CMD3["/cost — 查看费用"]
end
G -.-> CMD1
C2 -.-> CMD2
style S fill:#10b981,color:#fff
style C fill:#f59e0b,color:#fff
style E fill:#ef4444,color:#fff
```
### 6.2 实用命令
| 命令 | 作用 | 使用场景 |
|------|------|----------|
| `/compact` | 压缩历史消息，保留关键上下文 | 会话超过 30 分钟时 |
| `/compact 自定义提示` | 带指令压缩 | "保留数据库 schema，压缩其他" |
| `/clear` | 清空会话，重新开始 | 切换到完全不同的任务 |
| `/cost` | 查看 token 使用量和费用 | 每完成一个功能后检查 |
| `/model` | 切换模型 | 简单任务用 Haiku 省 token |
### 6.3 最佳实践
1. **一个功能一个会话**：完成一个功能（如"实现用户认证"）后，用 `/compact` 或开新会话
2. **善用 `/compact`**：它不是简单截断，而是智能总结之前的对话，保留关键决策和代码结构
3. **CLAUDE.md 越精炼越好**：过长的 CLAUDE.md 会持续消耗 token，控制在 100 行以内
---
## 第七步：实战案例——完整的 TaskFlow API
### 7.1 项目总览
经过上述步骤，你的项目结构应该是：
```
taskflow-api/
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── database.py
│ ├── models/
│ │ ├── __init__.py
│ │ └── task.py
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── task.py
│ ├── routers/
│ │ ├── __init__.py
│ │ └── tasks.py
│ └── crud/
│ ├── __init__.py
│ └── task.py
├── tests/
│ ├── __init__.py
│ └── test_tasks.py
├── .claude/
│ └── settings.json
├── .gitignore
├── CLAUDE.md
├── pyproject.toml
└── requirements.txt
```
### 7.2 用一条指令完成功能增强
尝试用一条自然语言指令添加新功能：
```
给 Task 模型添加 User 关联。一个 User 可以有多个 Task。
创建完整的 User CRUD 和路由，包含用户注册（密码用 bcrypt 哈希）。
在 Task 路由中添加按用户过滤的功能。
更新测试覆盖新功能。
```
Claude Code 会自动：
1. 创建 `app/models/user.py`
2. 创建 `app/schemas/user.py`
3. 创建 `app/crud/user.py`
4. 创建 `app/routers/users.py`
5. 修改 `app/models/task.py` 添加外键
6. 更新测试文件
这就是 Claude Code 的核心价值——**你只需要描述"做什么"，它负责"怎么做"**。
### 7.3 完整开发工作流
```mermaid
sequenceDiagram
participant D as 开发者
participant CC as Claude Code
participant FS as 文件系统
participant T as 终端
D->>CC: "创建 FastAPI 项目骨架"
CC->>FS: 创建目录和文件
CC->>D: 展示创建的文件列表
D->>CC: "定义 Task 数据模型"
CC->>FS: 写入 models/task.py
CC->>FS: 写入 schemas/task.py
D->>CC: "实现 CRUD 和路由"
CC->>FS: 写入 crud/task.py
CC->>FS: 写入 routers/tasks.py
D->>CC: "运行服务验证"
CC->>T: uvicorn app.main:app --reload
T-->>CC: 启动成功
CC-->>D: 服务运行在 :8000
D->>CC: "写测试并运行"
CC->>FS: 写入 tests/test_tasks.py
CC->>T: pytest -v
T-->>CC: 5 passed
CC-->>D: 所有测试通过 ✓
D->>CC: /compact
CC-->>D: 上下文已压缩
D->>CC: "添加 User 模型和认证"
Note over CC: 在压缩后的上下文中继续开发
```
---
## 第八步：Plan 模式的正确使用
### 8.1 什么时候用 Plan 模式
当你面对复杂需求时，先切换到 Plan 模式让 Claude 规划，再切换回正常模式执行：
```
# 按 Shift+Tab 切换到 Plan 模式
# 或者输入：
/plan
# 然后描述需求：
我需要给 API 添加 JWT 认证。请先规划实现方案，不要写代码。
```
Claude Code 会输出类似这样的规划：
```
## JWT 认证实现方案
1. 添加依赖：python-jose[cryptography], passlib[bcrypt]
2. 创建 app/core/security.py — JWT 编解码、密码哈希
3. 创建 app/core/config.py — 配置管理（SECRET_KEY 等）
4. 创建 app/routers/auth.py — 登录端点
5. 创建 app/deps.py — get_current_user 依赖
6. 在 Task 路由中添加认证保护
预估改动文件：7 个
预估时间：10 分钟
```
确认方案后，切换回正常模式执行：
```
# 按 Shift+Tab 切换回正常模式
# 然后说：
按方案执行
```
### 8.2 Plan 模式的优势
- **减少返工**：提前发现架构问题
- **节省 token**：规划阶段只读不写，消耗更少
- **提高质量**：结构化思考比即兴编码产出更好
---
## 第九步：常见问题与解决方案
### 问题 1：Claude Code 生成的代码不符合项目规范
**原因**：CLAUDE.md 不够具体或 Claude 没有读到最新的规则。
**解决**：
```
请重新阅读 CLAUDE.md，然后按照其中的代码规范重写 app/routers/tasks.py
```
或者直接在 `.claude/settings.json` 中通过 `projectRules` 强调关键规则。
### 问题 2：会话变慢或上下文溢出
**原因**：对话历史过长，token 消耗过大。
**解决**：
```bash
/compact 保留数据库模型定义和 API 路由结构，压缩其他历史
```
### 问题 3：Claude Code 频繁请求权限确认
**原因**：权限配置不完整。
**解决**：在 `.claude/settings.json` 的 `allow` 列表中添加常用的命令模式：
```json
{
"permissions": {
"allow": [
"Bash(python *)",
"Bash(pip *)",
"Bash(pytest *)",
"Bash(uvicorn *)",
"Bash(git *)",
"Bash(ls *)",
"Bash(cat *)",
"Read",
"Write",
"Edit"
]
}
}
```
### 问题 4：生成的测试依赖外部服务
**原因**：CLAUDE.md 中没有明确说明测试约束。
**解决**：在 CLAUDE.md 的"禁止事项"中添加：
```
- 测试必须使用 SQLite 内存数据库，不得依赖外部服务
```
---
## 第十步：从开发到部署准备
### 10.1 添加 Dockerfile
```
创建一个多阶段 Dockerfile，基于 python:3.11-slim。
第一阶段安装依赖，第二阶段复制代码并运行 uvicorn。
暴露 8000 端口。
```
生成的 `Dockerfile`：
```dockerfile
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```
### 10.2 添加 docker-compose.yml
```
创建 docker-compose.yml，包含 api 服务和 PostgreSQL 数据库服务。
添加环境变量配置。
```
### 10.3 提交代码
```
请帮我提交代码。提交信息要描述清楚本次创建的内容。
```
Claude Code 会生成规范的 commit message：
```
feat: init TaskFlow API with FastAPI
- Project skeleton with async SQLAlchemy + SQLite
- Task model with status and priority enums
- Full CRUD operations and RESTful routes
- Pydantic v2 schemas for request/response
- Async test suite with in-memory SQLite
- CLAUDE.md project configuration
Co-Authored-By: Claude Opus 4.6
```
---
## 核心工作流程总结
```text
flowchart TB
START[开始新项目] --> INSTALL[安装 Claude Code
npm i -g @anthropic-ai/claude-code]
INSTALL --> AUTH[认证
OAuth / API Key]
AUTH --> INIT[初始化项目
/init → CLAUDE.md]
INIT --> CONFIG[配置权限
.claude/settings.json]
CONFIG --> DEV[开发循环]
subgraph DEV[开发循环]
direction TB
PLAN[Plan模式
规划功能] --> CODE[正常模式
编写代码]
CODE --> TEST[运行测试
pytest -v]
TEST --> |失败| FIX[修复问题]
FIX --> TEST
TEST --> |通过| COMPACT[/compact
压缩上下文]
COMPACT --> |下一个功能| PLAN
end
DEV --> DEPLOY[部署准备
Dockerfile + CI]
style START fill:#7c3aed,color:#fff
style DEV fill:#3b82f6,color:#fff
style DEPLOY fill:#10b981,color:#fff
```
---
## 高效使用的十条原则
1. **CLAUDE.md 先行**：每次新建项目，第一件事就是写好 CLAUDE.md
2. **Plan → Execute**：复杂功能先规划后执行
3. **小步迭代**：一次只做一个功能，做完 `/compact` 再做下一个
4. **权限预设**：提前配置好 `allow/deny`，减少交互中断
5. **测试驱动**：让 Claude Code 先写测试再写实现
6. **`/compact` 习惯**：每完成一个功能就压缩一次上下文
7. **明确指令**：说"创建 RESTful API 路由"比"写个接口"好
8. **善用 `/cost`**：定期检查 token 消耗
9. **不要反复试错**：一次输出不对，换个描述方式而不是重复提问
10. **项目根目录启动**：始终在项目根目录运行 `claude`，确保上下文完整
---
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI 工具实战营、Python 后端训练营、开发者效率提升营 |
| 教学时长 | 半天（3-4 小时），含实操练习 |
| 学员基础要求 | 了解 Python 基础语法，用过终端 |
| 实操占比 | 70% 实操 + 30% 讲解 |
| 延伸方向 | 可衔接"Skills 开发"、"MCP 服务器开发"、"Agent 模式"等进阶课程 |
| 硬件要求 | 每人一台笔记本，能联网，已安装 Node.js 18+ 和 Python 3.11+ |
---
## 参考来源
1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门指南，涵盖安装、认证、基本使用
2. [Claude Code Tutorial for Beginners 2026 - dev.to](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 社区编写的 2026 年完整入门教程
3. [Setting Up a New Claude Code Project - builder.io](https://www.builder.io/blog/setting-up-claude-code-project) — 详细的项目配置指南，涵盖 CLAUDE.md、MCP、Skills
4. [Claude Code Token Optimization - Build to Launch](https://buildtolaunch.substack.com/p/claude-code-token-optimization) — Token 优化策略，上下文管理技巧
5. [Claude Code Permissions - Skills Playground](https://skillsplayground.com/guides/claude-code-permissions/) — 权限系统完整指南，沙箱配置
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
