448 lines
14 KiB
Markdown
448 lines
14 KiB
Markdown
---
|
||
created: "2026-06-27"
|
||
type: resource
|
||
tags: [claude-code, tutorial, hands-on, new-project, walkthrough, example]
|
||
source: "Anthropic 官方最佳实践 + 实操演练 · 2026-06-27"
|
||
---
|
||
|
||
# Claude Code 新项目实操教程 (贯穿示例)
|
||
|
||
> 配套理论篇:[[Claude Code 新项目开发最佳实践 (2026 调研)]]。
|
||
> 本篇是**手把手教程**:用一个真实小项目「短链接 API(url-shortener)」从**空文件夹 → 第一个 PR 合并**,
|
||
> 每一步都给出**真实命令、完整文件内容、与 Claude 的真实对话**。技术栈用 Node + TypeScript + Vitest(换成你的栈思路一样)。
|
||
|
||
---
|
||
|
||
## 目标产物
|
||
|
||
一个能 `POST /shorten {url}` 返回短码、`GET /:code` 302 跳转的 HTTP 服务。我们只做**第一个垂直切片**:`POST /shorten`,走完整 TDD + 四阶段闭环。
|
||
|
||
整个过程的目录最终长这样:
|
||
|
||
```
|
||
url-shortener/
|
||
├── .claude/
|
||
│ ├── settings.json # hooks:改完自动跑测试
|
||
│ ├── rules/
|
||
│ │ └── typescript.md # path-scoped 规则(只在改 .ts 时加载)
|
||
│ └── agents/
|
||
│ └── code-reviewer.md # 自定义子代理(也可用内置)
|
||
├── CLAUDE.md # 项目记忆:命令 + 约定
|
||
├── src/
|
||
│ ├── shorten.ts
|
||
│ └── server.ts
|
||
├── test/
|
||
│ └── shorten.test.ts
|
||
├── package.json
|
||
└── tsconfig.json
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 0 — 先建 git,再开 Claude
|
||
|
||
git 是回滚安全网。**先 init 再让 Claude 动手**,这样任何一步都能 `git checkout .` 退回。
|
||
|
||
```bash
|
||
mkdir url-shortener && cd url-shortener
|
||
git init
|
||
npm init -y
|
||
npm i -D typescript vitest @types/node tsx
|
||
npx tsc --init
|
||
git add -A && git commit -m "chore: 初始化空项目"
|
||
```
|
||
|
||
然后在该目录启动 Claude Code:
|
||
|
||
```bash
|
||
claude
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 1 — 用 `/init` 生成起始 CLAUDE.md,再亲手补全
|
||
|
||
在 Claude 里输入:
|
||
|
||
```
|
||
/init
|
||
```
|
||
|
||
它会扫描目录、检测到 TypeScript + Vitest,生成一份起始 `CLAUDE.md`。**起始版通常太泛**,你要立刻补上「**怎么跑测试 / lint / build**」——这是验证循环能跑起来的前提。手动把 `CLAUDE.md` 改成:
|
||
|
||
```markdown
|
||
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code when working in this repository.
|
||
|
||
## 命令
|
||
- 安装依赖:`npm install`
|
||
- 跑全部测试:`npm test` # 即 vitest run
|
||
- 跑单个测试文件:`npx vitest run test/shorten.test.ts`
|
||
- 跑单个用例:`npx vitest run -t "rejects an invalid url"`
|
||
- 类型检查:`npx tsc --noEmit`
|
||
- 启动服务:`npx tsx src/server.ts`
|
||
|
||
## 约定
|
||
- 纯函数放 src/,每个函数配同名 test/*.test.ts
|
||
- 不可变:函数返回新对象,绝不原地修改入参
|
||
- 短码用 base62、长度 7,生成逻辑必须可单测(不依赖网络/随机时不可测的部分要可注入)
|
||
- 错误处理:非法输入抛 `ValidationError`,不静默吞掉
|
||
|
||
## 测试策略(TDD)
|
||
先写失败测试 → 最小实现 → 重构。覆盖率目标 80%+。
|
||
```
|
||
|
||
> ⚠️ 在 `package.json` 里把 `"test": "vitest run"` 配好,否则 `npm test` 会报错。
|
||
|
||
把它提交:
|
||
|
||
```bash
|
||
git add CLAUDE.md package.json && git commit -m "docs: 添加 CLAUDE.md 与测试命令"
|
||
```
|
||
|
||
**为什么重要**:下次 Claude 想跑测试时,会直接读到 `npx vitest run -t "..."` 而不是瞎猜 `jest`、瞎猜路径。这一步省掉大量来回。
|
||
|
||
---
|
||
|
||
## 步骤 2 — 大规则拆进 `.claude/rules/`(path-scoped)
|
||
|
||
`CLAUDE.md` 要 < 200 行。TypeScript 细则不该塞进主文件,而是放 `.claude/rules/typescript.md`,**只在你改 `.ts` 文件时才按需加载**,省上下文。
|
||
|
||
`.claude/rules/typescript.md`:
|
||
|
||
```markdown
|
||
---
|
||
paths: ["**/*.ts"]
|
||
---
|
||
|
||
# TypeScript 规则(改 .ts 时加载)
|
||
|
||
- 开启 strict;不写 `any`,用 `unknown` + 收窄
|
||
- 导出函数必须有显式返回类型
|
||
- 用 `type` 而非 `interface` 定义数据形状(本项目约定)
|
||
- 校验在边界做:HTTP handler 入口校验 body,核心纯函数假设输入已校验
|
||
- 命名:函数 camelCase,类型 PascalCase,常量 UPPER_SNAKE_CASE
|
||
```
|
||
|
||
`paths` frontmatter 是关键:没有它就变成全局常驻、白占上下文。
|
||
|
||
---
|
||
|
||
## 步骤 3 — Explore:进 plan mode 只读探索(不写一行码)
|
||
|
||
按 **Shift+Tab** 循环模式,切到 **plan mode**(界面底部会显示 `plan mode on`)。plan mode 下 Claude **只能读、不能改**,逼它先看懂再动手。
|
||
|
||
你输入:
|
||
|
||
```
|
||
我们要做第一个切片:POST /shorten {url} -> {code}。
|
||
先只读探索:看现有 src/、CLAUDE.md、.claude/rules/typescript.md,
|
||
告诉我你打算怎么拆分文件、纯函数边界在哪、需要哪些测试用例。先别写代码。
|
||
```
|
||
|
||
Claude 在 plan mode 会回类似(读完文件后):
|
||
|
||
```
|
||
读完了。现状:src/ 为空,约定要求纯函数可单测、base62 短码长度 7。
|
||
拆分建议:
|
||
- src/shorten.ts:纯函数 shorten(url, idgen) —— 校验 url、用注入的 idgen 生成 code
|
||
- src/server.ts:HTTP 层,调用 shorten,负责 302/JSON 响应(薄)
|
||
纯函数边界:把"生成 id"作为参数注入,使 shorten 完全确定、可单测。
|
||
建议测试用例:
|
||
1. 合法 url -> 返回 7 位 base62 code
|
||
2. 非法 url(无 scheme)-> 抛 ValidationError
|
||
3. 同一 idgen 下相同输入 -> 相同输出(确定性)
|
||
4. code 字符集只含 [0-9a-zA-Z]
|
||
```
|
||
|
||
**关键点**:探索阶段产出的是「文件拆分 + 测试清单」,不是代码。idgen 作为参数注入,正是为了让纯函数可测——这种设计决策在探索阶段定下来,远比写完再返工省事。
|
||
|
||
---
|
||
|
||
## 步骤 4 — Plan:生成详细计划并亲手改
|
||
|
||
继续在 plan mode,让它把上面落成一份**有序计划**:
|
||
|
||
```
|
||
按 TDD 给我一份分步计划:先写哪个测试、再写哪段实现,顺序排好。
|
||
```
|
||
|
||
Claude 给出计划后,**按 Ctrl+G 可在编辑器里直接改这份计划**(比如你想调整用例顺序、加一条"超长 url 截断"的用例)。改完确认。一份典型计划:
|
||
|
||
```
|
||
1. 写 test/shorten.test.ts:用例 1-4(此时无实现,测试会失败)
|
||
2. 跑 npx vitest run test/shorten.test.ts → 确认 RED
|
||
3. 写 src/shorten.ts 最小实现:base62 编码 + url 校验
|
||
4. 跑测试 → GREEN
|
||
5. 重构:抽出 isValidUrl、BASE62 常量
|
||
6. 写 src/server.ts 薄 HTTP 层
|
||
7. tsc --noEmit + 全量测试
|
||
8. commit + PR
|
||
```
|
||
|
||
> 计划本身就是给「实现阶段」的 prompt —— 见 [[20260320100300 Plans as Prompts设计模式]]。
|
||
|
||
---
|
||
|
||
## 步骤 5 — Implement:TDD 红→绿→重构(看真实代码)
|
||
|
||
**退出 plan mode**(Shift+Tab 切回普通模式),让 Claude 按计划执行。下面是真实产物。
|
||
|
||
### 5a. 先写失败测试(RED)
|
||
|
||
`test/shorten.test.ts`:
|
||
|
||
```typescript
|
||
import { describe, it, expect } from "vitest";
|
||
import { shorten, ValidationError } from "../src/shorten";
|
||
|
||
// 注入一个确定性 idgen,使测试可重复
|
||
const fixedIdgen = () => 123456789;
|
||
|
||
describe("shorten", () => {
|
||
it("returns a 7-char base62 code for a valid url", () => {
|
||
const { code } = shorten("https://example.com", fixedIdgen);
|
||
expect(code).toHaveLength(7);
|
||
expect(code).toMatch(/^[0-9a-zA-Z]+$/);
|
||
});
|
||
|
||
it("rejects an invalid url", () => {
|
||
expect(() => shorten("not-a-url", fixedIdgen)).toThrow(ValidationError);
|
||
});
|
||
|
||
it("is deterministic for the same idgen", () => {
|
||
const a = shorten("https://example.com", fixedIdgen).code;
|
||
const b = shorten("https://example.com", fixedIdgen).code;
|
||
expect(a).toBe(b);
|
||
});
|
||
});
|
||
```
|
||
|
||
跑一下,**确认它失败**(这一步不能跳——你要看到 RED):
|
||
|
||
```bash
|
||
npx vitest run test/shorten.test.ts
|
||
# ❌ FAIL Cannot find module '../src/shorten' —— 正是预期的 RED
|
||
```
|
||
|
||
### 5b. 最小实现到通过(GREEN)
|
||
|
||
`src/shorten.ts`:
|
||
|
||
```typescript
|
||
export class ValidationError extends Error {}
|
||
|
||
const BASE62 = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
|
||
const CODE_LEN = 7;
|
||
|
||
function isValidUrl(url: string): boolean {
|
||
try {
|
||
const u = new URL(url);
|
||
return u.protocol === "http:" || u.protocol === "https:";
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
function toBase62(n: number): string {
|
||
let code = "";
|
||
let x = n;
|
||
while (code.length < CODE_LEN) {
|
||
code = BASE62[x % 62] + code;
|
||
x = Math.floor(x / 62);
|
||
}
|
||
return code.slice(-CODE_LEN);
|
||
}
|
||
|
||
export function shorten(
|
||
url: string,
|
||
idgen: () => number,
|
||
): { url: string; code: string } {
|
||
if (!isValidUrl(url)) {
|
||
throw new ValidationError(`Invalid url: ${url}`);
|
||
}
|
||
return { url, code: toBase62(idgen()) }; // 返回新对象,不改入参
|
||
}
|
||
```
|
||
|
||
再跑:
|
||
|
||
```bash
|
||
npx vitest run test/shorten.test.ts
|
||
# ✅ PASS 3 passed —— GREEN
|
||
```
|
||
|
||
### 5c. 薄 HTTP 层
|
||
|
||
`src/server.ts`:
|
||
|
||
```typescript
|
||
import { createServer } from "node:http";
|
||
import { shorten, ValidationError } from "./shorten";
|
||
|
||
const idgen = () => Date.now() + Math.floor(Math.random() * 1000);
|
||
|
||
createServer((req, res) => {
|
||
if (req.method === "POST" && req.url === "/shorten") {
|
||
let body = "";
|
||
req.on("data", (c) => (body += c));
|
||
req.on("end", () => {
|
||
try {
|
||
const { url } = JSON.parse(body); // 边界校验输入
|
||
const result = shorten(url, idgen);
|
||
res.writeHead(200, { "content-type": "application/json" });
|
||
res.end(JSON.stringify(result));
|
||
} catch (e) {
|
||
const status = e instanceof ValidationError ? 400 : 500;
|
||
res.writeHead(status, { "content-type": "application/json" });
|
||
res.end(JSON.stringify({ error: (e as Error).message }));
|
||
}
|
||
});
|
||
return;
|
||
}
|
||
res.writeHead(404).end();
|
||
}).listen(3000, () => console.log("listening on :3000"));
|
||
```
|
||
|
||
手动验一下:
|
||
|
||
```bash
|
||
npx tsx src/server.ts &
|
||
curl -s -XPOST localhost:3000/shorten -d '{"url":"https://example.com"}'
|
||
# {"url":"https://example.com","code":"0bygMqo"}
|
||
curl -s -XPOST localhost:3000/shorten -d '{"url":"bad"}'
|
||
# {"error":"Invalid url: bad"}
|
||
kill %1
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 6 — 把验证循环变成 Hook(确定性自动跑测试)
|
||
|
||
别依赖"记得跑测试"。配一个 **PostToolUse hook**:每次 Claude 改完 `.ts`,**自动跑测试**,结果回灌给它自我纠正。
|
||
|
||
`.claude/settings.json`:
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Edit|Write",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "if echo \"$CLAUDE_FILE_PATHS\" | grep -q '\\.ts$'; then npx vitest run 2>&1 | tail -20; fi"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
效果:Claude 一改 `.ts`,测试自动执行,失败输出直接进它的上下文,它会主动修。这就是"自给自足循环"——见 [[20260627062504 自给自足验证循环配合 TDD]]、[[20260319120100 Hook驱动优于提示词驱动]]。
|
||
|
||
> 想更严:再加一个 `PreToolUse` 在 git commit 前跑 `tsc --noEmit`,不过则拦截。
|
||
|
||
---
|
||
|
||
## 步骤 7 — 用子代理做独立代码审查(隔离上下文)
|
||
|
||
实现完,派一个**子代理**用全新上下文只看 diff 做审查——它不被你的实现思路"污染",更容易发现问题。
|
||
|
||
两种方式:
|
||
|
||
**A. 直接用内置/已装的(最简单)**——在主对话里说:
|
||
|
||
```
|
||
用 code-reviewer 子代理审查刚写的 src/shorten.ts 和 src/server.ts,
|
||
重点:不可变性、错误处理、base62 边界(n 极大时是否溢出)。
|
||
```
|
||
|
||
**B. 自定义一个项目子代理** `.claude/agents/code-reviewer.md`:
|
||
|
||
```markdown
|
||
---
|
||
name: code-reviewer
|
||
description: 审查本项目 TS 代码的质量与安全,改完代码后用。聚焦不可变、错误处理、边界。
|
||
tools: Read, Grep, Glob, Bash
|
||
---
|
||
|
||
你是资深 TS 评审。只读不改。按严重度(CRITICAL/HIGH/MEDIUM/LOW)输出问题,
|
||
每条给文件:行号 + 具体修法。重点:
|
||
- 是否原地修改了入参(违反不可变约定)
|
||
- 错误是否被静默吞掉
|
||
- 数值边界(base62 对超大整数是否丢精度)
|
||
- 输入是否在边界校验
|
||
最后给一句"可合并 / 需修改"结论。
|
||
```
|
||
|
||
> 何时用子代理 vs 主对话、为什么隔离上下文有效:[[20260320100100 上下文腐烂与全新窗口隔离]]、[[Claude Code 官方多Agent编排最佳实践 (2026)]]。
|
||
> 注意:子代理产生大量审查输出但只回摘要,不占用你主线上下文。
|
||
|
||
---
|
||
|
||
## 步骤 8 — Commit & PR
|
||
|
||
测试绿、审查过,收尾:
|
||
|
||
```bash
|
||
npx tsc --noEmit && npm test # 最后一道闸
|
||
git add -A
|
||
git commit -m "feat: 实现 POST /shorten 短链接生成
|
||
|
||
- shorten() 纯函数 + 注入式 idgen,完全可单测
|
||
- base62 7 位短码,http/https 校验,非法输入抛 ValidationError
|
||
- 薄 HTTP 层,400/500 区分
|
||
- 3 个用例覆盖:合法/非法/确定性"
|
||
git push -u origin HEAD
|
||
gh pr create --fill
|
||
```
|
||
|
||
让 Claude 起草 commit/PR 正文时,它会读 `git diff` 总结改动——这也是四阶段的最后一阶段 Commit。
|
||
|
||
---
|
||
|
||
## 回看:八步对应四阶段
|
||
|
||
| 步骤 | 四阶段 | 核心动作 |
|
||
|---|---|---|
|
||
| 0–2 | (准备) | git init、`/init`、写 CLAUDE.md 命令、拆 path-scoped rules |
|
||
| 3 | **Explore** | plan mode 只读,定文件拆分 + 测试清单 |
|
||
| 4 | **Plan** | TDD 分步计划,Ctrl+G 手改 |
|
||
| 5 | **Implement** | RED → GREEN → 重构,看真实代码 |
|
||
| 6 | (Implement 加固) | PostToolUse hook 自动验证 |
|
||
| 7 | (Implement 把关) | 子代理隔离审查 |
|
||
| 8 | **Commit** | tsc+test 闸门、描述性 commit、PR |
|
||
|
||
---
|
||
|
||
## 常见坑(实操踩过的)
|
||
|
||
- **跳过 RED**:不看测试失败就写实现,等于没验证测试本身有效。务必先跑出红。
|
||
- **CLAUDE.md 不写命令**:Claude 反复猜测试命令/框架,浪费大量轮次。命令是 CLAUDE.md 的第一优先级内容。
|
||
- **rules 不加 `paths`**:细则全局常驻,白烧上下文。能 scope 就 scope。
|
||
- **plan mode 忘了退**:停在 plan mode 时 Claude 改不了文件,会一直只给建议。Implement 前 Shift+Tab 切回。
|
||
- **hook 命令没过滤文件类型**:改个 README 也触发全量测试。用 `grep '\.ts$'` 限定。
|
||
- **把所有事塞一个 agent**:复杂流程拆"一任务一代理"更好调试。但多数日常编码留主对话即可,别为了用而用(多代理约 15x token)。
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [[Claude Code 新项目开发最佳实践 (2026 调研)]] —— 理论篇 / 出处
|
||
- [[Claude Code 多Agent编排 MOC]] —— 编排总入口
|
||
- [[20260627062503 Explore-Plan-Implement-Commit 四阶段工作流]]
|
||
- [[20260627062504 自给自足验证循环配合 TDD]]
|
||
- [[20260627062505 CLAUDE.md 是目录树拼接加载而非覆盖]]
|
||
- [[20260308223000 Claude Code Memory 日常最佳实践]]
|
||
|
||
## Source
|
||
|
||
- https://code.claude.com/docs/en/best-practices
|
||
- https://code.claude.com/docs/en/memory
|
||
- https://code.claude.com/docs/en/sub-agents
|
||
- https://code.claude.com/docs/en/hooks
|