feat(docs): add new documentation for mobile development, spec coding and claude agent sdk
Add comprehensive documentation for three new core skills: 1. Mobile development guide for Claude Code 2. Spec Coding methodology and workflow 3. Claude Agent SDK complete guide The new documentation covers: - Detailed explanations of concepts and architectures - Step-by-step implementation guides - Practical examples and use cases - Comparison tables and decision guides - Security considerations and best practices
This commit is contained in:
sanbuphy
@@ -569,6 +569,67 @@ Token 使用：45,230 / 200,000 (22.6%)
|
||||
2. **优化 .claudeignore**：将不相关的文件（如 node_modules、构建产物）加入忽略列表
|
||||
3. **决定何时压缩**：当使用率超过 70% 时，考虑使用 `/compact`
|
||||
|
||||
### 技巧 11：/resume 恢复会话 —— 切换多任务对话
|
||||
|
||||
当你在处理多个任务时，可能会开启多段对话。`/resume` 能让你在当前聊天中快速切换回之前的会话，而不需要退出重新启动。
|
||||
|
||||
**使用方式：**
|
||||
|
||||
```
|
||||
/resume
|
||||
```
|
||||
|
||||
**工作原理：**
|
||||
|
||||
Claude Code 会自动记录你之前的对话会话。当你使用 `/resume` 时，它会切换回上一段会话的上下文，保留之前的所有讨论内容和状态。
|
||||
|
||||
**使用场景：**
|
||||
|
||||
**场景 A：多任务并行处理**
|
||||
```
|
||||
# 任务 1：修复 bug
|
||||
claude> 修复登录页面的验证问题
|
||||
# ... 进行了一段对话...
|
||||
|
||||
# 任务 2：添加新功能（新开一段会话）
|
||||
claude> 添加用户注册功能
|
||||
# ... 进行了另一段对话...
|
||||
|
||||
# 切换回任务 1
|
||||
claude> /resume
|
||||
# 继续之前的 bug 修复工作
|
||||
```
|
||||
|
||||
**场景 B：临时查询后返回**
|
||||
```
|
||||
claude> 解释一下这个算法
|
||||
# ... 讨论算法...
|
||||
|
||||
claude> /resume
|
||||
# 自动切换回之前的代码开发工作
|
||||
```
|
||||
|
||||
**场景 C：对话中断后继续**
|
||||
```
|
||||
claude> 继续之前的工作
|
||||
# 如果你之前中断了某个任务，可以用 /resume 返回
|
||||
```
|
||||
|
||||
**与相关命令的对比：**
|
||||
|
||||
| 命令 | 作用 | 使用场景 |
|
||||
|------|------|----------|
|
||||
| `/resume` | 在当前聊天中切换回上一段会话 | 多任务并行，需要来回切换 |
|
||||
| `claude -c` | 继续最近的一次会话 | 退出后重新连接同一会话 |
|
||||
| `claude -r` | 恢复上一段会话 | 退出后恢复到之前的会话状态 |
|
||||
| `双击 Esc` | 回退到上一次对话状态 | 撤销最近一轮对话 |
|
||||
|
||||
**使用建议：**
|
||||
|
||||
1. **多任务管理**：当你需要在多个任务之间切换时，使用 `/resume` 比重新描述上下文更高效
|
||||
2. **会话记忆**：每段会话都有独立的上下文，`/resume` 能帮你保留这些上下文
|
||||
3. **配合 /compact**：在长会话中，可以先 `/compact` 压缩，再 `/resume` 切换，保持上下文清晰
|
||||
|
||||
---
|
||||
|
||||
## 核心配置
|
||||
|
||||
@@ -0,0 +1,689 @@
|
||||
# Claude Agent SDK 完全指南
|
||||
|
||||
## 引言
|
||||
|
||||
你可能已经用过 Claude 的基础 API——发一条消息，拿一个回复，就像聊天一样。但如果你想让 Claude 帮你读文件、跑命令、搜代码、改 bug，然后自己验证结果，再继续改……这种"自主干活"的能力，基础 API 是做不到的。
|
||||
|
||||
Claude Agent SDK 就是为这个场景而生的。它把 Claude Code 的全部能力——读写文件、执行命令、搜索代码、编辑文件、浏览网页——封装成了一个可编程的库。你不需要自己写工具调用循环，Claude 会自主执行工具、自主迭代，直到任务真正完成。
|
||||
|
||||
一句话总结：基础 SDK 是"你问它答"，Agent SDK 是"你下单它干活"。
|
||||
|
||||
---
|
||||
|
||||
## 它和基础 SDK 到底有什么区别？
|
||||
|
||||
先看代码，一目了然：
|
||||
|
||||
```python
|
||||
# 基础 anthropic SDK：你得自己写循环处理工具调用
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
response = client.messages.create(
|
||||
model="claude-sonnet-4-6",
|
||||
max_tokens=1024,
|
||||
messages=[{"role": "user", "content": "修复 auth.py 的 bug"}],
|
||||
tools=[...] # 你得自己定义工具
|
||||
)
|
||||
# Claude 说要调用某个工具
|
||||
while response.stop_reason == "tool_use":
|
||||
result = your_tool_executor(response.tool_use) # 你得自己执行
|
||||
response = client.messages.create(tool_result=result, **params) # 你得自己喂回去
|
||||
```
|
||||
|
||||
```python
|
||||
# Agent SDK：一行搞定，Claude 自己读文件、找 bug、改代码
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions
|
||||
|
||||
async for message in query(
|
||||
prompt="修复 auth.py 的 bug",
|
||||
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
|
||||
):
|
||||
print(message) # Claude 自己读文件、定位问题、修改代码
|
||||
```
|
||||
|
||||
区别很明显：
|
||||
|
||||
| 对比项 | 基础 anthropic SDK | Claude Agent SDK |
|
||||
|--------|-------------------|-----------------|
|
||||
| 工具执行 | 你自己写 | Claude 自己来 |
|
||||
| 工具循环 | 你自己实现 | 内置 agent loop |
|
||||
| 内置工具 | 无，全靠你定义 | 读写文件、Bash、搜索等开箱即用 |
|
||||
| 上下文管理 | 你自己维护 | 自动压缩、自动管理 |
|
||||
| 适合场景 | 聊天、生成、简单 tool use | 自主完成复杂任务 |
|
||||
|
||||
---
|
||||
|
||||
## 安装和配置
|
||||
|
||||
### 安装
|
||||
|
||||
Python 需要 3.10+，TypeScript 需要 Node.js 18+：
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install claude-agent-sdk
|
||||
|
||||
# TypeScript
|
||||
npm install @anthropic-ai/claude-agent-sdk
|
||||
```
|
||||
|
||||
### 认证
|
||||
|
||||
设置 API Key 环境变量即可：
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=your-api-key
|
||||
```
|
||||
|
||||
也支持云平台认证：
|
||||
- AWS Bedrock：设置 `CLAUDE_CODE_USE_BEDROCK=1` + AWS 凭证
|
||||
- Google Vertex AI：设置 `CLAUDE_CODE_USE_VERTEX=1` + GCP 凭证
|
||||
- Microsoft Azure：设置 `CLAUDE_CODE_USE_FOUNDRY=1` + Azure 凭证
|
||||
|
||||
### 自定义 API 地址
|
||||
|
||||
如果你用的是代理、网关或者自建的 API 端点，可以通过 `env` 参数修改默认的 API URL：
|
||||
|
||||
```python
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions
|
||||
|
||||
async for message in query(
|
||||
prompt="Hello",
|
||||
options=ClaudeAgentOptions(
|
||||
env={
|
||||
"ANTHROPIC_BASE_URL": "https://your-proxy.example.com",
|
||||
"ANTHROPIC_API_KEY": "your-api-key",
|
||||
}
|
||||
),
|
||||
):
|
||||
print(message)
|
||||
```
|
||||
|
||||
`ClaudeAgentOptions` 没有直接的 `base_url` 参数，但 `env` 字段可以传入任意环境变量给底层的 Claude Code CLI。常用的环境变量：
|
||||
|
||||
| 环境变量 | 用途 |
|
||||
|---------|------|
|
||||
| `ANTHROPIC_BASE_URL` | 自定义 API 端点（代理、网关） |
|
||||
| `ANTHROPIC_API_KEY` | API 密钥 |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | 替代认证 token |
|
||||
| `ANTHROPIC_CUSTOM_HEADERS` | 自定义请求头 |
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
Agent SDK 的运行原理可以用一句话概括：**收集上下文 → 执行动作 → 验证结果 → 重复**。
|
||||
|
||||
这和人类开发者的工作方式一模一样——先看代码，再改代码，然后跑测试看结果，不对就继续改。Agent SDK 把这个循环自动化了。
|
||||
|
||||
### 两种使用模式
|
||||
|
||||
**模式一：`query()` 函数 —— 无状态，适合单次任务**
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions
|
||||
|
||||
async def main():
|
||||
async for message in query(
|
||||
prompt="这个目录下有哪些文件？",
|
||||
options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
**模式二：`ClaudeSDKClient` —— 有状态，适合多轮对话**
|
||||
|
||||
当你需要保持上下文、多轮交互时使用。比如先让 Claude 读一个模块，再让它找所有调用这个模块的地方——第二轮它还记得第一轮读了什么。
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions
|
||||
|
||||
async def main():
|
||||
session_id = None
|
||||
|
||||
# 第一轮：读认证模块
|
||||
async for message in query(
|
||||
prompt="读一下认证模块的代码",
|
||||
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
|
||||
):
|
||||
if hasattr(message, "subtype") and message.subtype == "init":
|
||||
session_id = message.session_id
|
||||
|
||||
# 第二轮：基于上下文继续工作
|
||||
async for message in query(
|
||||
prompt="找出所有调用它的地方",
|
||||
options=ClaudeAgentOptions(resume=session_id),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 内置工具：开箱即用
|
||||
|
||||
这是 Agent SDK 最爽的地方——你不需要自己实现任何工具，Claude 直接就能用：
|
||||
|
||||
| 工具 | 功能 | 典型用途 |
|
||||
|------|------|---------|
|
||||
| Read | 读取文件 | 看代码、读配置 |
|
||||
| Write | 创建文件 | 生成新文件 |
|
||||
| Edit | 精确编辑文件 | 改 bug、重构 |
|
||||
| Bash | 执行终端命令 | 跑测试、装依赖、git 操作 |
|
||||
| Glob | 按模式找文件 | `**/*.py`、`src/**/*.ts` |
|
||||
| Grep | 正则搜索文件内容 | 找函数定义、找 TODO |
|
||||
| WebSearch | 搜索网页 | 查文档、找方案 |
|
||||
| WebFetch | 抓取网页内容 | 读在线文档 |
|
||||
| Task | 启动子 agent | 并行处理子任务 |
|
||||
|
||||
通过 `allowed_tools` 参数控制 agent 能用哪些工具：
|
||||
|
||||
```python
|
||||
# 只读 agent：只能看，不能改
|
||||
options = ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Glob", "Grep"],
|
||||
permission_mode="bypassPermissions"
|
||||
)
|
||||
|
||||
# 全能 agent：能读能写能跑命令
|
||||
options = ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 高级功能
|
||||
|
||||
### Hooks：在关键节点插入你的逻辑
|
||||
|
||||
Hooks 让你在 agent 执行的关键时刻插入自定义代码——比如记录日志、拦截危险操作、审计文件变更。
|
||||
|
||||
支持的 Hook 类型：`PreToolUse`（工具执行前）、`PostToolUse`（工具执行后）、`Stop`（agent 停止时）、`SessionStart`、`SessionEnd` 等。
|
||||
|
||||
```python
|
||||
from datetime import datetime
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
|
||||
|
||||
# 每次文件被修改时，记录到审计日志
|
||||
async def log_file_change(input_data, tool_use_id, context):
|
||||
file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
|
||||
with open("./audit.log", "a") as f:
|
||||
f.write(f"{datetime.now()}: modified {file_path}\n")
|
||||
return {}
|
||||
|
||||
async def main():
|
||||
async for message in query(
|
||||
prompt="重构 utils.py 提升可读性",
|
||||
options=ClaudeAgentOptions(
|
||||
permission_mode="acceptEdits",
|
||||
hooks={
|
||||
"PostToolUse": [
|
||||
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
|
||||
]
|
||||
},
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
```
|
||||
|
||||
实际用途：
|
||||
- 审计日志：记录 agent 的每一步操作
|
||||
- 安全拦截：阻止 agent 修改某些关键文件
|
||||
- 通知推送：agent 完成任务时发送消息
|
||||
- 成本监控：统计工具调用次数和 token 消耗
|
||||
|
||||
### 子 Agent：把大任务拆给专家
|
||||
|
||||
当任务足够复杂时，你可以定义多个专门的子 agent，让主 agent 把子任务分配给它们。每个子 agent 有自己的指令和工具权限，互不干扰。
|
||||
|
||||
```python
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
|
||||
|
||||
async for message in query(
|
||||
prompt="用 code-reviewer agent 审查这个项目的代码质量",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Glob", "Grep", "Task"],
|
||||
agents={
|
||||
"code-reviewer": AgentDefinition(
|
||||
description="专业代码审查员，负责质量和安全审查",
|
||||
prompt="分析代码质量，找出潜在问题并给出改进建议。",
|
||||
tools=["Read", "Glob", "Grep"],
|
||||
),
|
||||
"test-writer": AgentDefinition(
|
||||
description="测试专家，负责编写单元测试",
|
||||
prompt="为缺少测试的函数编写单元测试。",
|
||||
tools=["Read", "Write", "Bash"],
|
||||
),
|
||||
},
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
```
|
||||
|
||||
子 agent 的消息会带有 `parent_tool_use_id` 字段，方便你追踪哪些消息来自哪个子 agent。
|
||||
|
||||
### MCP 集成：接入外部世界
|
||||
|
||||
通过 Model Context Protocol（MCP），你的 agent 可以连接数据库、浏览器、第三方 API 等外部系统。社区已经有[数百个 MCP 服务器](https://github.com/modelcontextprotocol/servers)可以直接用。
|
||||
|
||||
```python
|
||||
# 接入 Playwright，让 agent 能操作浏览器
|
||||
async for message in query(
|
||||
prompt="打开 example.com 并描述你看到了什么",
|
||||
options=ClaudeAgentOptions(
|
||||
mcp_servers={
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["@playwright/mcp@latest"]
|
||||
}
|
||||
}
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
```
|
||||
|
||||
常见的 MCP 集成场景：
|
||||
- Playwright：浏览器自动化，爬取网页、填写表单
|
||||
- PostgreSQL/MySQL：直接查询和操作数据库
|
||||
- Slack/Email：发送通知和消息
|
||||
- GitHub：操作 PR、Issue、代码仓库
|
||||
|
||||
---
|
||||
|
||||
## 能用来做什么？实战场景
|
||||
|
||||
理解了功能之后，最重要的问题是：这东西到底能干嘛？下面是经过社区验证的真实场景。
|
||||
|
||||
### 场景一：自动修 Bug Agent
|
||||
|
||||
给它一个 bug 描述，它自己找代码、定位问题、修复、跑测试验证：
|
||||
|
||||
```python
|
||||
async for message in query(
|
||||
prompt="用户反馈登录时偶尔报 500 错误，请排查 src/auth/ 目录下的代码并修复",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
|
||||
permission_mode="acceptEdits",
|
||||
),
|
||||
):
|
||||
print(message)
|
||||
```
|
||||
|
||||
Claude 会自己 grep 错误日志、读相关代码、找到 bug、改代码、跑测试确认修复。
|
||||
|
||||
### 场景二：代码审查 Agent
|
||||
|
||||
构建一个只读的代码审查 agent，审查代码质量但不做任何修改：
|
||||
|
||||
```python
|
||||
async for message in query(
|
||||
prompt="审查 src/ 目录下的代码，关注安全漏洞、性能问题和代码规范",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Glob", "Grep"],
|
||||
permission_mode="bypassPermissions",
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
```
|
||||
|
||||
### 场景三：CI/CD 集成
|
||||
|
||||
在持续集成流水线中，让 agent 自动分析失败的测试并尝试修复：
|
||||
|
||||
```python
|
||||
async for message in query(
|
||||
prompt="运行 npm test，分析失败的测试用例，修复代码使所有测试通过",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Edit", "Bash", "Glob"],
|
||||
max_turns=20,
|
||||
),
|
||||
):
|
||||
print(message)
|
||||
```
|
||||
|
||||
这是 Agent SDK 相比 CLI 最大的优势场景——CLI 适合人坐在终端前交互，SDK 适合嵌入到自动化流程中。
|
||||
|
||||
### 场景四：研究 Agent
|
||||
|
||||
让 agent 搜索网络、阅读文档、综合信息并输出报告：
|
||||
|
||||
```python
|
||||
async for message in query(
|
||||
prompt="调研 2026 年主流的 Python Web 框架，对比 FastAPI、Django、Litestar，输出技术选型报告到 report.md",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["WebSearch", "WebFetch", "Write"],
|
||||
),
|
||||
):
|
||||
print(message)
|
||||
```
|
||||
|
||||
### 场景五：带浏览器的全栈 Agent
|
||||
|
||||
通过 MCP 接入 Playwright，agent 不仅能写代码，还能打开浏览器验证效果：
|
||||
|
||||
```python
|
||||
async for message in query(
|
||||
prompt="修复首页的样式问题，然后打开浏览器截图确认效果",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Edit", "Bash"],
|
||||
mcp_servers={
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["@playwright/mcp@latest"]
|
||||
}
|
||||
},
|
||||
),
|
||||
):
|
||||
print(message)
|
||||
```
|
||||
|
||||
### 场景速查表
|
||||
|
||||
| 场景 | 核心工具 | 难度 |
|
||||
|------|---------|------|
|
||||
| 自动修 Bug | Read, Edit, Bash, Grep | 入门 |
|
||||
| 代码审查 | Read, Glob, Grep | 入门 |
|
||||
| CI/CD 自动修复 | Read, Edit, Bash | 中级 |
|
||||
| 技术调研报告 | WebSearch, WebFetch, Write | 入门 |
|
||||
| 浏览器自动化 | MCP (Playwright) | 中级 |
|
||||
| 多 Agent 协作 | Task + AgentDefinition | 高级 |
|
||||
| 数据库操作 | MCP (PostgreSQL/MySQL) | 中级 |
|
||||
| 邮件/通知助手 | MCP (Slack/Email) | 中级 |
|
||||
|
||||
---
|
||||
|
||||
## 什么时候该用 Agent SDK？
|
||||
|
||||
不是所有场景都需要 Agent SDK。选对工具很重要：
|
||||
|
||||
| 你想做的事 | 该用什么 |
|
||||
|-----------|---------|
|
||||
| 简单对话、文本生成、翻译 | 基础 `anthropic` SDK |
|
||||
| 单次 tool use（查天气、算数） | 基础 `anthropic` SDK |
|
||||
| 自主完成多步骤开发任务 | Agent SDK |
|
||||
| 嵌入 CI/CD 流水线 | Agent SDK |
|
||||
| 构建能操作文件系统的应用 | Agent SDK |
|
||||
| 日常交互式开发 | Claude Code CLI |
|
||||
| 一次性快速任务 | Claude Code CLI |
|
||||
|
||||
简单来说：如果你的任务需要 Claude "自己动手干活"（读文件、改代码、跑命令），用 Agent SDK。如果只是"问答"，用基础 SDK 就够了。
|
||||
|
||||
---
|
||||
|
||||
## 企业级实战：构建代码质量守护流水线
|
||||
|
||||
前面的场景都是单个 agent 做单件事。但在真实的企业环境中，你需要的是一条完整的流水线——多个 agent 串联协作，每个环节有明确的输入输出，有审计、有回滚、有通知。
|
||||
|
||||
下面我们构建一个真实场景：**每次 PR 提交后，自动触发代码审查 → 安全扫描 → 自动修复 → 测试验证 → 生成报告**的完整流水线。
|
||||
|
||||
### 架构设计
|
||||
|
||||
```
|
||||
PR 提交
|
||||
│
|
||||
▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 代码审查 │───▶│ 安全扫描 │───▶│ 自动修复 │
|
||||
│ Agent │ │ Agent │ │ Agent │
|
||||
│ (只读) │ │ (只读) │ │ (可写) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ 测试验证 │───▶│ 报告生成 │
|
||||
│ Agent │ │ Agent │
|
||||
│ (Bash) │ │ (Write) │
|
||||
└─────────────┘ └─────────────┘
|
||||
│
|
||||
▼
|
||||
Slack 通知
|
||||
```
|
||||
|
||||
核心思想：**每个 agent 只做一件事，权限最小化，结果串联传递**。
|
||||
|
||||
### 第一步：定义流水线框架
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import json
|
||||
from datetime import datetime
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
|
||||
|
||||
# 审计日志：记录每个 agent 的每一步操作
|
||||
audit_log = []
|
||||
|
||||
async def audit_hook(input_data, tool_use_id, context):
|
||||
audit_log.append({
|
||||
"time": datetime.now().isoformat(),
|
||||
"tool": input_data.get("tool_name"),
|
||||
"input": input_data.get("tool_input", {}),
|
||||
})
|
||||
return {}
|
||||
|
||||
# 通用 hook 配置：所有 agent 共享审计能力
|
||||
audit_hooks = {
|
||||
"PostToolUse": [HookMatcher(matcher=".*", hooks=[audit_hook])]
|
||||
}
|
||||
```
|
||||
|
||||
### 第二步：代码审查 Agent（只读）
|
||||
|
||||
```python
|
||||
async def run_code_review(pr_diff: str) -> str:
|
||||
"""只读 agent，审查代码质量，输出结构化报告"""
|
||||
result_text = ""
|
||||
async for message in query(
|
||||
prompt=f"""审查以下 PR diff，从这几个维度分析：
|
||||
1. 代码规范：命名、格式、注释
|
||||
2. 逻辑问题：边界条件、空指针、竞态
|
||||
3. 性能隐患：N+1 查询、内存泄漏、不必要的循环
|
||||
4. 可维护性：函数过长、职责不清、魔法数字
|
||||
|
||||
PR Diff:
|
||||
{pr_diff}
|
||||
|
||||
输出 JSON 格式：{{"issues": [{{"severity": "high/medium/low", "file": "...", "line": ..., "description": "..."}}], "summary": "..."}}""",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Glob", "Grep"],
|
||||
permission_mode="bypassPermissions",
|
||||
hooks=audit_hooks,
|
||||
max_turns=10,
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
result_text = message.result
|
||||
return result_text
|
||||
```
|
||||
|
||||
### 第三步：安全扫描 Agent（只读）
|
||||
|
||||
```python
|
||||
async def run_security_scan() -> str:
|
||||
"""只读 agent，专注安全漏洞扫描"""
|
||||
result_text = ""
|
||||
async for message in query(
|
||||
prompt="""扫描项目代码中的安全漏洞：
|
||||
1. SQL 注入、XSS、CSRF
|
||||
2. 硬编码的密钥或凭证
|
||||
3. 不安全的依赖版本
|
||||
4. 权限校验缺失
|
||||
|
||||
输出 JSON：{{"vulnerabilities": [{{"severity": "critical/high/medium", "type": "...", "file": "...", "description": "...", "fix_suggestion": "..."}}]}}""",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Glob", "Grep", "Bash"],
|
||||
permission_mode="bypassPermissions",
|
||||
hooks=audit_hooks,
|
||||
max_turns=15,
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
result_text = message.result
|
||||
return result_text
|
||||
```
|
||||
|
||||
### 第四步：自动修复 Agent（可写）
|
||||
|
||||
```python
|
||||
async def run_auto_fix(review_result: str, security_result: str) -> str:
|
||||
"""可写 agent，根据审查和扫描结果自动修复代码"""
|
||||
result_text = ""
|
||||
async for message in query(
|
||||
prompt=f"""根据以下审查结果修复代码：
|
||||
|
||||
代码审查报告：
|
||||
{review_result}
|
||||
|
||||
安全扫描报告：
|
||||
{security_result}
|
||||
|
||||
修复规则：
|
||||
1. 只修复 severity 为 high 或 critical 的问题
|
||||
2. 每次修改后运行相关测试确认没有破坏现有功能
|
||||
3. 不要重构无关代码，只做最小修复
|
||||
4. 修复完成后输出修改文件列表""",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
|
||||
permission_mode="acceptEdits",
|
||||
hooks=audit_hooks,
|
||||
max_turns=30,
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
result_text = message.result
|
||||
return result_text
|
||||
```
|
||||
|
||||
### 第五步：测试验证 + 报告生成
|
||||
|
||||
```python
|
||||
async def run_test_and_report(fix_result: str) -> str:
|
||||
"""运行测试，生成最终报告"""
|
||||
result_text = ""
|
||||
async for message in query(
|
||||
prompt=f"""执行以下操作：
|
||||
1. 运行完整测试套件（npm test 或 pytest）
|
||||
2. 统计测试通过率
|
||||
3. 生成 Markdown 格式的质量报告到 pr-report.md，包含：
|
||||
- 代码审查发现的问题数量和严重程度分布
|
||||
- 安全漏洞数量
|
||||
- 自动修复的内容：{fix_result}
|
||||
- 测试通过率
|
||||
- 最终结论：是否建议合并""",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Bash", "Write", "Glob"],
|
||||
hooks=audit_hooks,
|
||||
max_turns=15,
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
result_text = message.result
|
||||
return result_text
|
||||
```
|
||||
|
||||
### 第六步：串联整条流水线
|
||||
|
||||
```python
|
||||
import subprocess
|
||||
|
||||
async def run_pipeline():
|
||||
"""完整的 PR 质量守护流水线"""
|
||||
print("🔍 阶段 1/4：代码审查...")
|
||||
pr_diff = subprocess.run(
|
||||
["git", "diff", "main...HEAD"], capture_output=True, text=True
|
||||
).stdout
|
||||
review_result = await run_code_review(pr_diff)
|
||||
|
||||
print("🛡️ 阶段 2/4：安全扫描...")
|
||||
security_result = await run_security_scan()
|
||||
|
||||
print("🔧 阶段 3/4：自动修复...")
|
||||
fix_result = await run_auto_fix(review_result, security_result)
|
||||
|
||||
print("✅ 阶段 4/4：测试验证 + 生成报告...")
|
||||
report = await run_test_and_report(fix_result)
|
||||
|
||||
# 保存审计日志
|
||||
with open("audit-log.json", "w") as f:
|
||||
json.dump(audit_log, f, indent=2, ensure_ascii=False)
|
||||
|
||||
print(f"流水线完成，审计日志已保存（共 {len(audit_log)} 条操作记录）")
|
||||
return report
|
||||
|
||||
asyncio.run(run_pipeline())
|
||||
```
|
||||
|
||||
### 企业级设计思考
|
||||
|
||||
这条流水线体现了几个关键的企业级设计原则：
|
||||
|
||||
**权限最小化**：代码审查和安全扫描 agent 只有只读权限，不可能误改代码。只有自动修复 agent 才有写权限，而且限定了 `acceptEdits` 模式。
|
||||
|
||||
**可审计**：每个 agent 的每一步操作都通过 Hook 记录到审计日志。出了问题可以回溯是哪个 agent 在什么时间做了什么操作。
|
||||
|
||||
**结果串联**：上一个 agent 的输出是下一个 agent 的输入。代码审查的结果喂给自动修复，自动修复的结果喂给测试验证。每个环节都有明确的输入输出契约。
|
||||
|
||||
**成本可控**：每个 agent 都设置了 `max_turns` 限制，防止某个环节失控空转。生产环境中还可以加上 `max_budget_usd` 做预算控制。
|
||||
|
||||
**可扩展**：想加新环节？比如加一个"文档检查 agent"或"性能基准测试 agent"，只需要写一个新函数，插入流水线即可。
|
||||
|
||||
这个模式可以直接嵌入 GitHub Actions 或 GitLab CI，每次 PR 自动触发，真正实现"AI 驱动的代码质量守护"。
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
Agent SDK 提供了清晰的异常类型，方便你在生产环境中做好容错：
|
||||
|
||||
```python
|
||||
from claude_agent_sdk import query, CLINotFoundError, ProcessError
|
||||
|
||||
try:
|
||||
async for msg in query(prompt="分析代码"):
|
||||
print(msg)
|
||||
except CLINotFoundError:
|
||||
print("Claude Code CLI 未安装，请先安装")
|
||||
except ProcessError as e:
|
||||
print(f"进程异常退出，退出码: {e.exit_code}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
Claude Agent SDK 的核心价值是把"模型推理"升级为"可控执行"。它不只是生成文本，而是能在一个可审计、可约束的工具系统中真正完成任务。
|
||||
|
||||
记住 Anthropic 官方博客中的一句话：Agent SDK 的设计哲学是"给 agent 一台电脑，让它像人一样工作"。
|
||||
|
||||
好的 agent 应用 = 清晰的工具设计 + 明确的任务边界 + 适当的人工监督。工具给了 agent 能力，边界给了它约束，监督给了你信心。三者缺一不可。
|
||||
|
||||
---
|
||||
|
||||
## 参考资料
|
||||
|
||||
### 官方资源
|
||||
|
||||
- [Agent SDK 官方文档](https://platform.claude.com/docs/en/agent-sdk/overview) - 最权威的参考
|
||||
- [GitHub - claude-agent-sdk-python](https://github.com/anthropics/claude-code-sdk-python) - Python SDK 源码
|
||||
- [GitHub - claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript) - TypeScript SDK 源码
|
||||
- [示例 Agent 项目](https://github.com/anthropics/claude-agent-sdk-demos) - 邮件助手、研究 agent 等
|
||||
|
||||
### 博客与教程
|
||||
|
||||
- [Building agents with the Claude Agent SDK](https://claude.com/blog/building-agents-with-the-claude-agent-sdk) - Anthropic 官方工程博客，讲解设计哲学和架构
|
||||
- [Claude Agent SDK Python 学习指南](https://redreamality.com/blog/claude-agent-sdk-python-) - 中文友好，从零开始的完整教程
|
||||
- [Claude Agent SDK 完整教程](https://blog.wenhaofree.com/en/posts/articles/claude-agent-sdk-tutorial/) - 工具系统、Agent Loop、可控执行实战
|
||||
- [12 个 Agent SDK 实用场景](https://skywork.ai/blog/claude-agent-sdk-use-cases-2025/) - 覆盖编码、数据、自动化等
|
||||
- [Step-by-Step Agent 教程](https://skywork.ai/blog/how-to-use-claude-agent-sdk-step-by-step-ai-agent-tutorial/) - TypeScript + Python 双轨教程
|
||||
@@ -0,0 +1,904 @@
|
||||
# Claude Code 手机远程开发
|
||||
|
||||
## 引言
|
||||
|
||||
想象一下这些场景：你在通勤的地铁上突然想到一个绝妙的 bug 修复方案；你在咖啡厅排队时收到线上故障的紧急通知；你在陪女朋友逛街时想看看 AI 构建的项目进展如何。
|
||||
|
||||
传统开发模式下，这些场景意味着你需要找个地方打开电脑，或者无奈地把事情推迟。但在 AI 辅助编程时代，规则变了。Claude Code 的出现让我们可以把开发环境装进口袋，随时随地保持生产力。
|
||||
|
||||
2025 年夏天，随着 Claude Code 的普及，开发者们开始探索各种"手机编程"方案。从简单的 Termux 本地运行，到复杂的 SSH + Tailscale 远程连接，再到专门的 Happy Coder 应用，一个完整的移动开发生态逐渐形成。
|
||||
|
||||
本章要解决的核心问题是：如何让 Claude Code 跟随你的手机，成为真正的"口袋开发助手"。
|
||||
|
||||
---
|
||||
|
||||
## 核心原理：手机开发的架构模式
|
||||
|
||||
在介绍各种方案之前，先理解问题的本质。
|
||||
|
||||
### 为什么手机开发是个问题？
|
||||
|
||||
传统的 IDE（如 VS Code、IntelliJ）需要完整的操作系统环境、强大的 CPU、大量内存和存储空间。手机虽然性能越来越强，但在开发体验上仍有天然限制：
|
||||
|
||||
**输入限制**：虚拟键盘输入代码效率低，复杂语法容易出错
|
||||
|
||||
**屏幕限制**：小屏幕难以同时查看代码、终端和浏览器
|
||||
|
||||
**环境限制**：手机无法运行完整的开发工具链（编译器、数据库、调试器）
|
||||
|
||||
**连接限制**：移动网络不稳定，SSH 连接容易断开
|
||||
|
||||
### 核心思想：瘦客户端架构
|
||||
|
||||
所有手机开发方案的核心思想都是：手机只是"控制台"，真正的开发工作在别处完成。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 手机 │ │ 主机/云端 │ │
|
||||
│ │ (控制端) │ ────────► │ (执行端) │ │
|
||||
│ │ │ 指令/结果 │ │ │
|
||||
│ │ • 输入指令 │ │ • 运行 CLI │ │
|
||||
│ │ • 查看输出 │ │ • 执行代码 │ │
|
||||
│ │ • 审查更改 │ │ • 访问文件 │ │
|
||||
│ └─────────────┘ └─────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
这种架构让手机只需要负责"人机交互"，把繁重的计算工作交给主机或云端。
|
||||
|
||||
---
|
||||
|
||||
## 方案一：iOS 官方 App
|
||||
|
||||
2025 年 10 月，Anthropic 正式在 iOS App 中推出了 Claude Code 移动版，这是最简单的手机开发方案。
|
||||
|
||||
### 地区限制
|
||||
|
||||
⚠️ **重要提示**：Claude App 在中国大陆地区**无法直接使用**。
|
||||
|
||||
如果你在中国大陆，推荐直接使用 **Happy Coder**（方案二），它可以通过配置国内 API 中转服务正常工作。
|
||||
|
||||
如果你有海外 Apple ID，可以通过切换地区下载 Claude App。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────────┐
|
||||
│ iOS App │ ──────────────────► │ Anthropic 云端 │
|
||||
│ (手机) │ HTTPS + OAuth │ Claude Code │
|
||||
└─────────────┘ └────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────┐
|
||||
│ GitHub API │
|
||||
└───────────────┘
|
||||
```
|
||||
|
||||
你的手机 App 只是发送指令，所有代码执行都在 Anthropic 的云端沙盒中进行，结果通过 GitHub 同步。
|
||||
|
||||
### 基本使用
|
||||
|
||||
**前提条件**：
|
||||
|
||||
- iPhone iOS 15 或更高版本
|
||||
- Claude Pro/Team/Enterprise 订阅（免费版不支持）
|
||||
- GitHub 账号
|
||||
|
||||
**使用步骤**：
|
||||
|
||||
1. 从 App Store 下载 Claude App
|
||||
2. 登录你的 Anthropic 账号
|
||||
3. 在 App 中找到"Code"标签页
|
||||
4. 通过 OAuth 连接你的 GitHub 仓库
|
||||
5. 开始创建任务
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是配置零门槛、体验流畅、有推送通知。缺点是只支持 iOS、主要支持 GitHub、功能相对受限（不能访问本地文件系统）、中国大陆无法使用。
|
||||
|
||||
---
|
||||
|
||||
## 方案二：Happy Coder
|
||||
|
||||
Happy Coder 是一个为 Claude Code 和 Codex 设计的开源移动和 Web 客户端，支持端到端加密，可以从任何地方控制你的 AI 编程助手。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Happy App │ ────────► │ Happy Server │ ◄──────── │happy-coder │
|
||||
│ (手机/Web) │ 加密WebSocket│ (中继服务器) │ WebSocket │ (电脑CLI) │
|
||||
└─────────────┘ └─────────────┘ └──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│Claude Code │
|
||||
│ CLI │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
在电脑上运行 `happy` 代替 `claude` 启动 AI 编程助手。当需要在手机上控制时，会话会自动切换到远程模式。电脑上按任意键即可切回本地控制。
|
||||
|
||||
### 安装和使用
|
||||
|
||||
**步骤 1：下载 App**
|
||||
|
||||
| 平台 | 链接 |
|
||||
|------|------|
|
||||
| iOS | [App Store](https://apps.apple.com/us/app/happy-claude-code-client/id6748571505) |
|
||||
| Android | [Google Play](https://play.google.com/store/apps/details?id=com.ex3ndr.happy) |
|
||||
| Web | [app.happy.engineering](https://app.happy.engineering) |
|
||||
|
||||
**步骤 2：电脑安装 CLI**
|
||||
|
||||
```bash
|
||||
npm install -g happy-coder
|
||||
```
|
||||
|
||||
**步骤 3：启动并配对**
|
||||
|
||||
```bash
|
||||
# 在项目目录中运行
|
||||
cd ~/my-project
|
||||
happy
|
||||
|
||||
# 会显示配对二维码
|
||||
```
|
||||
|
||||
**步骤 4：手机扫码配对**
|
||||
|
||||
打开 Happy App，扫描电脑上显示的二维码。配对成功后即可在手机上控制 Claude Code。
|
||||
|
||||
**步骤 5：使用**
|
||||
|
||||
```bash
|
||||
# 启动 Claude Code
|
||||
happy
|
||||
|
||||
# 或启动 Codex
|
||||
happy codex
|
||||
```
|
||||
|
||||
### 资源链接
|
||||
|
||||
- [GitHub 项目](https://github.com/slopus/happy) - 源代码
|
||||
- [文档网站](https://happy.engineering/docs) - 使用文档
|
||||
- [Discord 社区](https://discord.gg/fX9WBAhyfD) - 社区讨论
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是配置简单、跨平台支持、端到端加密、开源可审计。缺点是需要依赖第三方中继服务器、手机应用需要自行验证可用性。
|
||||
|
||||
---
|
||||
|
||||
## 方案三：HAPI
|
||||
|
||||
HAPI 是 Happy Coder 的替代方案，采用本地优先的设计理念，支持无缝切换设备和多种 AI 模型。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ HAPI App │ ────────► │ HAPI Server │ ◄──────── │ hapi │
|
||||
│(手机/PWA/ │ WireGuard │ (自建中继) │ WireGuard │ (电脑CLI) │
|
||||
│ Telegram) │ + TLS │ │ + TLS │ │
|
||||
└─────────────┘ └─────────────┘ └──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│Claude Code │
|
||||
│ / Codex / │
|
||||
│ Gemini等 │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
HAPI 使用 WireGuard 配合 TLS 实现端到端加密，所有通信经过加密中继服务器。你可以自建中继服务器，完全掌控数据流。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **无缝切换**：在电脑和手机之间无缝切换控制，按任意键即可回到本地控制
|
||||
- **原生优先**：使用原生技术封装移动应用，提供流畅的交互体验
|
||||
- **AFK 审批**：离开电脑时，手机可以接收审批请求，无需中断工作流
|
||||
- **多模型支持**：支持 Claude Code、Codex、Gemini、OpenCode 等多种 AI 编程助手
|
||||
- **随时随地终端**：通过 PWA、Telegram Mini App 等多种方式访问
|
||||
- **语音控制**：支持语音输入指令，解放双手
|
||||
|
||||
### 安装和使用
|
||||
|
||||
**步骤 1：启动中继服务器**
|
||||
|
||||
```bash
|
||||
# 在你的服务器上运行（或使用 npx 直接启动）
|
||||
npx @twsxtd/hapi hub --relay
|
||||
```
|
||||
|
||||
**步骤 2：电脑安装 CLI**
|
||||
|
||||
```bash
|
||||
# 在项目目录中运行
|
||||
cd ~/my-project
|
||||
npx @twsxtd/hapi
|
||||
|
||||
# 或全局安装
|
||||
npm install -g @twsxtd/hapi
|
||||
hapi
|
||||
```
|
||||
|
||||
**步骤 3：配对设备**
|
||||
|
||||
按照终端提示，在手机上打开 HAPI App 并扫描二维码完成配对。
|
||||
|
||||
**步骤 4：访问方式**
|
||||
|
||||
| 访问方式 | 说明 |
|
||||
|---------|------|
|
||||
| Web PWA | 浏览器访问，支持安装到桌面 |
|
||||
| Telegram Mini App | 在 Telegram 内直接使用 |
|
||||
| 移动应用 | 原生应用体验（如已发布） |
|
||||
|
||||
### 与 Happy Coder 的区别
|
||||
|
||||
| 特性 | Happy Coder | HAPI |
|
||||
|------|-------------|------|
|
||||
| 设计理念 | 云端优先 | 本地优先 |
|
||||
| 加密方式 | WebSocket + E2E | WireGuard + TLS |
|
||||
| 多模型支持 | Claude Code, Codex | Claude, Codex, Gemini, OpenCode |
|
||||
| 访问方式 | iOS/Android/Web | PWA, Telegram, 更多 |
|
||||
| 语音控制 | ❌ | ✅ 支持 |
|
||||
| AFK 审批 | ❌ | ✅ 支持 |
|
||||
| 自建中继 | ⚠️ 需手动部署 | ✅ 开箱即用 |
|
||||
|
||||
### 资源链接
|
||||
|
||||
- [GitHub 项目](https://github.com/tiann/hapi) - 源代码
|
||||
- [PWA 使用文档](https://github.com/tiann/hapi/blob/main/docs/pwa.md) - PWA 安装和使用
|
||||
- [工作原理](https://github.com/tiann/hapi/blob/main/docs/how-it-works.md) - 技术实现细节
|
||||
- [语音助手](https://github.com/tiann/hapi/blob/main/docs/voice.md) - 语音控制功能
|
||||
- [为什么选择 HAPI](https://github.com/tiann/hapi/blob/main/docs/why-hapi.md) - 设计理念
|
||||
- [常见问题](https://github.com/tiann/hapi/blob/main/docs/faq.md) - FAQ
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是本地优先设计、多模型支持、端到端加密、支持语音控制、可自建中继。缺点是项目相对较新、社区生态仍在发展中。
|
||||
|
||||
---
|
||||
|
||||
## 方案四：SSH + Tailscale + Tmux
|
||||
|
||||
这是最适合专业开发者的方案，通过 SSH 远程连接到你的开发机器，配合 Tmux 保持会话持久化。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 手机 │ ────────► │ Tailscale │ ◄──────── │ 电脑 │
|
||||
│ (SSH客户端)│ VPN P2P │ 中继/打洞 │ VPN P2P │ (开发机) │
|
||||
└─────────────┘ └─────────────┘ └──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Tmux │
|
||||
│ (会话保持) │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
Tailscale 创建一个点对点 VPN 网络，让你在任何网络环境下都能直接访问家里的电脑。Tmux 确保即使 SSH 断开，Claude Code 仍在后台运行。
|
||||
|
||||
### 为什么需要 Tailscale？
|
||||
|
||||
**传统的 SSH 连接问题**：
|
||||
|
||||
```
|
||||
手机 (4G) ──XX──> 路由器 NAT ──XX──> 家里电脑
|
||||
(无法穿透) (内网隔离)
|
||||
```
|
||||
|
||||
你的电脑在内网，手机在外网无法直接访问。传统的解决方案是配置端口转发和动态 DNS，过程复杂且有安全风险。
|
||||
|
||||
**Tailscale 的解决方案**：
|
||||
|
||||
```
|
||||
手机 (4G) ──► Tailscale 中继 ──◄── 家里电脑
|
||||
(自动打洞或中继)
|
||||
```
|
||||
|
||||
Tailscale 使用 NAT 打洞技术，如果打洞失败会自动使用中继服务器，全程加密。
|
||||
|
||||
### 完整配置步骤
|
||||
|
||||
**步骤 1：在电脑上安装 Tailscale**
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install --cask tailscale
|
||||
|
||||
# 或下载安装包
|
||||
# https://tailscale.com/download
|
||||
```
|
||||
|
||||
**步骤 2：登录并获取 IP**
|
||||
|
||||
```bash
|
||||
# 启动 Tailscale
|
||||
sudo tailscale up
|
||||
|
||||
# 查看 Tailscale IP
|
||||
tailscale ip -4
|
||||
# 输出示例: 100.x.x.x
|
||||
```
|
||||
|
||||
**步骤 3：在手机上安装 Tailscale**
|
||||
|
||||
从 App Store 或 Google Play 下载 Tailscale，用同一账号登录。
|
||||
|
||||
**步骤 4：安装并配置 Tmux**
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install tmux
|
||||
|
||||
# 创建配置文件 ~/.tmux.conf
|
||||
cat > ~/.tmux.conf << 'EOF'
|
||||
# 启用鼠标支持
|
||||
set -g mouse on
|
||||
|
||||
# 设置默认终端模式为 256 色
|
||||
set -g default-terminal "screen-256color"
|
||||
|
||||
# 更改按键绑定为 Ctrl+A（可选）
|
||||
unbind C-b
|
||||
set -g prefix C-a
|
||||
|
||||
# 简化的分割面板快捷键
|
||||
bind v split-window -h
|
||||
bind h split-window
|
||||
```
|
||||
|
||||
**步骤 5：创建持久化会话**
|
||||
|
||||
```bash
|
||||
# 创建名为 "claude" 的会话
|
||||
tmux new -s claude
|
||||
|
||||
# 在这个会话中启动 Claude Code
|
||||
cd ~/my-project
|
||||
claude
|
||||
|
||||
# 分离会话（不关闭）
|
||||
# 按 Ctrl+B 然后按 D
|
||||
```
|
||||
|
||||
**步骤 6：手机 SSH 客户端连接**
|
||||
|
||||
推荐使用的 SSH 客户端：
|
||||
|
||||
| 客户端 | 平台 | 特点 |
|
||||
|--------|------|------|
|
||||
| Blink Shell | iOS | 支持 MOSH，适合不稳定网络 |
|
||||
| Termius | iOS/Android | 跨平台，界面美观 |
|
||||
| a-Shell | iOS | 免费，轻量级 |
|
||||
|
||||
连接配置：
|
||||
|
||||
```
|
||||
Host: 100.x.x.x (你的 Tailscale IP)
|
||||
Port: 22
|
||||
Username: 你的电脑用户名
|
||||
```
|
||||
|
||||
连接后附加到 Tmux 会话：
|
||||
|
||||
```bash
|
||||
tmux attach -t claude
|
||||
```
|
||||
|
||||
### 进阶技巧
|
||||
|
||||
**防止电脑休眠**：
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
caffeinate -dimsu &
|
||||
|
||||
# 或设置系统偏好 > 能源节能 > 防止自动休眠
|
||||
```
|
||||
|
||||
**使用 MOSH 应对不稳定网络**：
|
||||
|
||||
MOSH (Mobile Shell) 是专门为移动网络优化的 SSH 替代品，支持网络切换无缝恢复。
|
||||
|
||||
```bash
|
||||
# 在电脑上安装
|
||||
brew install mosh
|
||||
|
||||
# 在手机上使用 MOSH 连接
|
||||
# Blink Shell 原生支持 MOSH
|
||||
```
|
||||
|
||||
**一键连接脚本**：
|
||||
|
||||
在 SSH 客户端中设置启动命令：
|
||||
|
||||
```bash
|
||||
tmux attach -t claude || tmux new -s claude
|
||||
```
|
||||
|
||||
这样连接后会自动附加到现有会话，或创建新会话。
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是功能完整、体验与桌面一致、支持所有开发工具。缺点是配置相对复杂、需要电脑保持运行。
|
||||
|
||||
---
|
||||
|
||||
## 方案五：Termux 本地运行
|
||||
|
||||
如果你是 Android 用户，可以直接在手机上运行 Claude Code，无需连接外部设备。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ ┌─────────────┐ │
|
||||
│ │ Termux │ │
|
||||
│ │ (Linux环境) │ │
|
||||
│ │ │ │
|
||||
│ │ • Node.js │ │
|
||||
│ │ • Claude │ │
|
||||
│ │ Code CLI │ │
|
||||
│ │ │ │
|
||||
│ │ • 项目文件 │ │
|
||||
│ │ • Git │ │
|
||||
│ └─────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────┐ │
|
||||
│ │Anthropic API│ │
|
||||
│ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Termux 是 Android 上的终端模拟器和 Linux 环境，你可以直接在上面安装 Node.js 和 Claude Code。
|
||||
|
||||
### 安装步骤
|
||||
|
||||
**重要**：从 [F-Droid](https://f-droid.org/) 下载 Termux，不要用 Google Play 版本（已过时）。
|
||||
|
||||
**步骤 1：安装基础工具**
|
||||
|
||||
```bash
|
||||
# 更新包管理器
|
||||
pkg update && pkg upgrade
|
||||
|
||||
# 安装开发工具
|
||||
pkg install git nodejs python vim
|
||||
```
|
||||
|
||||
**步骤 2：安装 Claude Code**
|
||||
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
**步骤 3：配置环境**
|
||||
|
||||
```bash
|
||||
# 创建工作目录
|
||||
mkdir -p ~/projects
|
||||
cd ~/projects
|
||||
|
||||
# 初始化项目
|
||||
git clone https://github.com/your-repo.git
|
||||
cd your-repo
|
||||
|
||||
# 启动 Claude Code
|
||||
claude
|
||||
```
|
||||
|
||||
**步骤 4：配置外部键盘（推荐）**
|
||||
|
||||
在 Termux 中：
|
||||
|
||||
```bash
|
||||
# 启用扩展键行
|
||||
# 长按屏幕 > More > Extra keys row
|
||||
|
||||
# 配置快捷键
|
||||
# 在 ~/.termux/termux.properties 中添加
|
||||
extra-keys = [['ESC','/','-','HOME','UP','END','PGUP','~'], \
|
||||
['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN','|']]
|
||||
```
|
||||
|
||||
### 性能考虑
|
||||
|
||||
| 任务类型 | Android 表现 |
|
||||
|---------|-------------|
|
||||
| Web 开发 (HTML/CSS/JS) | ✅ 优秀 |
|
||||
| Python 脚本 | ✅ 优秀 |
|
||||
| Node.js 应用 | ✅ 良好 |
|
||||
| 运行测试套件 | ⚠️ 中等 |
|
||||
| 编译大型项目 | ❌ 不推荐 |
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是完全本地化、无需网络、完全掌控。缺点是手机性能有限、输入体验差、仅限 Android。
|
||||
|
||||
---
|
||||
|
||||
## 方案六：Claude Code UI
|
||||
|
||||
Claude Code UI（又名 CloudCLI）是一个开源项目，为 Claude Code 提供 Web 界面，支持手机浏览器访问。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 手机浏览器 │ ────────► │ Web 服务器 │ ◄──────── │Claude Code │
|
||||
│ │ HTTP/HTTPS │ (localhost) │ 调用 │ CLI │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
在电脑上运行 Web 服务器，手机通过浏览器访问。这需要内网穿透或局域网访问。
|
||||
|
||||
### 安装和使用
|
||||
|
||||
**步骤 1：安装**
|
||||
|
||||
```bash
|
||||
# 一键启动（推荐）
|
||||
npx @siteboon/claude-code-ui
|
||||
|
||||
# 或全局安装
|
||||
npm install -g @siteboon/claude-code-ui
|
||||
claude-code-ui
|
||||
```
|
||||
|
||||
**步骤 2：访问界面**
|
||||
|
||||
服务器默认运行在 `http://localhost:3001`
|
||||
|
||||
**步骤 3：手机访问**
|
||||
|
||||
方法 A - 局域网访问（同一 WiFi）：
|
||||
|
||||
```bash
|
||||
# 启动时绑定所有接口
|
||||
claude-code-ui --host 0.0.0.0
|
||||
|
||||
# 手机访问
|
||||
http://电脑局域网IP:3001
|
||||
```
|
||||
|
||||
方法 B - 使用 ngrok 内网穿透：
|
||||
|
||||
```bash
|
||||
# 安装 ngrok
|
||||
brew install ngrok
|
||||
|
||||
# 启动隧道
|
||||
ngrok http 3001
|
||||
|
||||
# 手机访问 ngrok 提供的 URL
|
||||
```
|
||||
|
||||
### 功能
|
||||
|
||||
- 响应式设计，支持移动端
|
||||
- 内置聊天界面
|
||||
- 文件浏览器
|
||||
- Git 操作界面
|
||||
- 会话管理
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是有图形界面、功能完整。缺点是需要内网穿透（除非局域网）、配置相对复杂。
|
||||
|
||||
---
|
||||
|
||||
## 方案七：云端开发环境
|
||||
|
||||
如果你没有常开的电脑，可以使用云端开发环境，Claude Code 运行在云服务器上。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 手机 │ ────────► │ 云端容器 │ ─────────► │Claude Code │
|
||||
│ (浏览器/App)│ HTTPS │ (DevBox) │ │ CLI │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
云容器中预装了 Claude Code，你通过浏览器或手机 App 访问。
|
||||
|
||||
### 使用 Sealos DevBox
|
||||
|
||||
**步骤 1：创建环境**
|
||||
|
||||
访问 [Sealos DevBox](https://sealos.io/devbox)，选择 Claude Code 模板创建环境。
|
||||
|
||||
**步骤 2：启动开发环境**
|
||||
|
||||
约 30-60 秒后环境就绪，你得到一个 Web 终端。
|
||||
|
||||
**步骤 3：配置 Claude API**
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
```
|
||||
|
||||
**步骤 4：连接 Happy App**
|
||||
|
||||
```bash
|
||||
# 安装 happy-coder（已预装）
|
||||
npm install -g happy-coder
|
||||
|
||||
# 生成配对二维码
|
||||
happy
|
||||
```
|
||||
|
||||
手机扫码后即可使用。
|
||||
|
||||
### 云端方案对比
|
||||
|
||||
| 平台 | Claude Code | 移动优化 | 启动时间 | 定价 |
|
||||
|------|------------|----------|----------|------|
|
||||
| Sealos DevBox | ✅ 预装 | ✅ Happy | ~60秒 | 按量付费 |
|
||||
| GitHub Codespaces | ⚠️ 手动 | ⚠️ 浏览器 | ~2-3分钟 | 免费额度+按小时 |
|
||||
| Gitpod | ⚠️ 手动 | ⚠️ 浏览器 | ~1-2分钟 | 免费额度+按小时 |
|
||||
| Replit | ❌ | ✅ 原生App | 即时 | 免费+订阅 |
|
||||
|
||||
### 优缺点
|
||||
|
||||
优点是无需本地电脑、环境一致、可扩展。缺点是需要付费、依赖网络、代码在云端。
|
||||
|
||||
---
|
||||
|
||||
## 方案对比与选择
|
||||
|
||||
各种方案各有特点，适合不同场景。
|
||||
|
||||
### 对比表
|
||||
|
||||
| 方案 | 难度 | 需要内网穿透 | 费用 | 适用场景 |
|
||||
|------|------|-------------|------|----------|
|
||||
| iOS 官方 App | 简单 | ❌ | $20/月 | 快速查看、简单任务 |
|
||||
| Happy Coder | 较简单 | ❌ | 免费 | 日常使用、便利性 |
|
||||
| HAPI | 中等 | ❌ | 免费 | 多模型支持、本地优先 |
|
||||
| SSH + Tailscale | 较复杂 | ❌ | 免费 | 专业开发、完整功能 |
|
||||
| Termux | 中等 | ❌ | 免费 | Android 本地开发 |
|
||||
| Claude Code UI | 中等 | ✅ 需要 | 免费 | 需要 Web 界面 |
|
||||
| 云端 DevBox | 简单 | ❌ | 按量付费 | 无本地电脑 |
|
||||
|
||||
### 选择指南
|
||||
|
||||
**如果你在中国大陆**：推荐使用 **Happy Coder**，可以通过配置国内 API 中转服务正常工作。
|
||||
|
||||
**如果你追求便利性**：Happy Coder 最省心，扫码即用。
|
||||
|
||||
**如果需要多模型支持**：HAPI 支持多种 AI 编程助手，适合需要在不同模型间切换的开发者。
|
||||
|
||||
**如果你有常开的电脑**：SSH + Tailscale 是最佳选择，体验最完整。
|
||||
|
||||
**如果你是 iPhone 用户（非大陆）**：官方 App 是最简单的入门方式。
|
||||
|
||||
**如果你只有 Android 手机**：Termux 可以让你完全在手机上开发。
|
||||
|
||||
**如果你没有电脑**：云端 DevBox 是理想选择。
|
||||
|
||||
---
|
||||
|
||||
## 安全性与隐私
|
||||
|
||||
手机开发涉及代码在网络上传输，需要特别注意安全。
|
||||
|
||||
### 中继服务器的风险
|
||||
|
||||
使用 Happy Coder、HAPI 等需要中继的服务时，考虑以下问题：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ 中继服务器能看到什么？ │
|
||||
│ │
|
||||
│ • 加密前的数据（如果端到端加密实现不当） │
|
||||
│ • 元数据（何时连接、连接多长时间） │
|
||||
│ • 你的 API Key（如果配置不当） │
|
||||
│ │
|
||||
│ 中继服务器能做什么？ │
|
||||
│ │
|
||||
│ • 记录你的代码内容 │
|
||||
│ • 窃取 API 密钥 │
|
||||
│ • 注入恶意命令 │
|
||||
│ • 把你的设备当作节点攻击其他人 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 安全最佳实践
|
||||
|
||||
**1. 代码敏感度分级**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ 公开项目/学习代码 ──► 可以用任何方案 │
|
||||
│ │
|
||||
│ 私人项目 ──► 推荐 SSH+Tailscale 或 自建中继 │
|
||||
│ │
|
||||
│ 商业代码 ──► 只用 SSH+Tailscale，禁用所有第三方中继 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**2. 密钥管理**
|
||||
|
||||
```bash
|
||||
# ❌ 不要在代码中硬编码密钥
|
||||
const apiKey = "sk-ant-xxxxx"
|
||||
|
||||
# ✅ 使用环境变量
|
||||
const apiKey = process.env.ANTHROPIC_API_KEY
|
||||
|
||||
# ✅ 使用 .env 文件（加入 .gitignore）
|
||||
ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||||
```
|
||||
|
||||
**3. 使用沙盒**
|
||||
|
||||
Claude Code 支持沙盒模式，限制其访问范围：
|
||||
|
||||
```bash
|
||||
claude --sandbox /path/to/project
|
||||
```
|
||||
|
||||
**4. 自建中继**
|
||||
|
||||
如果你使用 Happy Coder，可以考虑自建中继服务器：
|
||||
|
||||
```bash
|
||||
# 克隆项目（包含服务器代码）
|
||||
git clone https://github.com/slopus/happy.git
|
||||
cd happy
|
||||
|
||||
# 部署服务器代码到你的 VPS
|
||||
# 具体步骤参考项目文档
|
||||
```
|
||||
|
||||
**5. 使用 Headscale**
|
||||
|
||||
Headscale 是 Tailscale 的开源实现，可以自建中继服务器：
|
||||
|
||||
```bash
|
||||
# Docker 一键部署
|
||||
docker run -d \
|
||||
--name headscale \
|
||||
-v /srv/headscale:/etc/headscale \
|
||||
-p 3478:3478/udp \
|
||||
-p 8080:8080 \
|
||||
headscale/headscale:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 需要内网穿透吗？
|
||||
|
||||
大部分现代方案**不需要**内网穿透：
|
||||
|
||||
| 方案 | 原理 |
|
||||
|------|------|
|
||||
| Happy Coder | 中继模式，双方主动连接服务器 |
|
||||
| HAPI | 中继模式，WireGuard + TLS |
|
||||
| Tailscale | NAT 打洞或中继 |
|
||||
| iOS App | 云端执行 |
|
||||
| Claude Code UI | 需要（被动入站） |
|
||||
|
||||
### 为什么中继模式不需要穿透？
|
||||
|
||||
```
|
||||
主动出站（NAT允许）：
|
||||
电脑 ──► 中继服务器 ✓
|
||||
|
||||
主动入站（NAT阻挡）：
|
||||
外部 ──► 电脑 ✗
|
||||
|
||||
中继模式的巧妙之处：
|
||||
双方都主动连接中继服务器，都不需要入站！
|
||||
```
|
||||
|
||||
### 手机开发会影响电池吗？
|
||||
|
||||
不同方案耗电不同：
|
||||
|
||||
| 方案 | 耗电量 | 原因 |
|
||||
|------|--------|------|
|
||||
| SSH 终端 | 低 | 只是文本显示 |
|
||||
| iOS App | 中 | 云端执行，手机只做控制 |
|
||||
| Termux | 高 | 本地运行 CLI |
|
||||
| 浏览器 | 中 | Web 界面渲染 |
|
||||
|
||||
建议长时间使用时连接充电器。
|
||||
|
||||
### 网络断开会怎样？
|
||||
|
||||
| 方案 | 网络断开影响 |
|
||||
|------|-------------|
|
||||
| SSH + Tmux | Claude 继续运行，重连后可恢复 |
|
||||
| Happy Coder | 自动重连 |
|
||||
| HAPI | 自动重连 |
|
||||
| iOS App | 云端继续，App 提示断开 |
|
||||
| Termux | 会话中断 |
|
||||
|
||||
### 能在手机上编译大型项目吗？
|
||||
|
||||
不推荐。手机 CPU 和内存有限，大型编译会导致：
|
||||
|
||||
- 手机发烫
|
||||
- 电池快速消耗
|
||||
- 编译时间过长
|
||||
|
||||
建议将编译任务放到远程服务器或云端执行。
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
Claude Code 手机开发的核心思想是：**手机只是控制端，真正的开发工作在别处完成**。
|
||||
|
||||
选择哪种方案取决于你的具体需求。
|
||||
|
||||
如果你在中国大陆，推荐 **Happy Coder**，配置国内 API 中转即可使用。
|
||||
|
||||
如果想要最省心的方案，用 **Happy Coder**。扫码即用，推送通知，设备切换流畅。
|
||||
|
||||
如果需要多模型支持或本地优先设计，用 **HAPI**。支持多种 AI 编程助手，可自建中继。
|
||||
|
||||
如果想要最完整的开发体验，用 **SSH + Tailscale**。配置稍复杂，但功能最全，体验与桌面一致。
|
||||
|
||||
如果是 iOS 用户（非大陆），**官方 App** 是最简单的入门方式。
|
||||
|
||||
如果是 Android 用户，**Termux** 让你完全在手机上开发。
|
||||
|
||||
如果没有常开的电脑，**云端 DevBox** 是理想选择。
|
||||
|
||||
无论哪种方案，都要注意安全性：敏感代码要慎用第三方中继，API 密钥要妥善管理，重要项目最好用自建中继。
|
||||
|
||||
---
|
||||
|
||||
## 参考资料
|
||||
|
||||
### 官方资源
|
||||
|
||||
- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) - Claude Code 的完整官方文档
|
||||
- [Claude iOS App](https://apps.apple.com/app/claude/id6473753684) - 官方 iOS 应用
|
||||
|
||||
### 开源项目
|
||||
|
||||
- [slopus/happy](https://github.com/slopus/happy) (2.5k⭐) - Happy Coder 移动客户端
|
||||
- [tiann/hapi](https://github.com/tiann/hapi) - HAPI 本地优先的多模型 AI 编程助手
|
||||
- [siteboon/claudecodeui](https://github.com/siteboon/claudecodeui) - Claude Code UI (CloudCLI)
|
||||
- [juanfont/headscale](https://github.com/juanfont/headscale) (19k⭐) - Tailscale 的开源实现
|
||||
|
||||
### 中文教程
|
||||
|
||||
- [随时随地大小编，手机也能配置Claude Code](https://m.blog.csdn.net/haa_y/article/details/151156494) - Termux 配置教程
|
||||
- [口袋里的 AI 实验室：永不掉线的 Claude Code 移动工作流](https://www.cnblogs.com/swizard/p/19308983) - Tmux + Docker 方案
|
||||
- [陪女朋友逛街时，我带上了 Claude Code](https://post.m.smzdm.com/p/a3r7d63d/) - Tailscale 远程连接
|
||||
- [手机就能写上线级App](https://m.toutiao.com/article/7611823834756301318/) - 移动开发实战案例
|
||||
|
||||
### 英文资源
|
||||
|
||||
- [The Definitive Guide to Using Claude Code on Your Phone | Sealos Blog](https://sealos.io/blog/claude-code-on-phone/) - 最全面的手机开发指南
|
||||
- [SSH + Tailscale + Termius Complete Guide](https://m.blog.csdn.net/Lvyizhuo/article/details/157692953) - 远程连接详细教程
|
||||
|
||||
### 工具下载
|
||||
|
||||
- [Tailscale](https://tailscale.com/download) - 点对点 VPN 工具
|
||||
- [Termux (F-Droid)](https://f-droid.org/en/packages/com.termux/) - Android 终端模拟器
|
||||
- [Blink Shell](https://blink.sh/) - iOS SSH 客户端（支持 MOSH）
|
||||
- [Termius](https://termius.com/) - 跨平台 SSH 客户端
|
||||
@@ -0,0 +1,613 @@
|
||||
# 从 Vibe Coding 到 Spec Coding：AI 编程的进化之路
|
||||
|
||||
> "Code is a lossy projection of intent."
|
||||
> 代码是意图的有损投影。
|
||||
> —— Sean Grove, OpenAI, AI Engineer World's Fair 2025
|
||||
|
||||
## Spec Coding 的核心理念：万物皆 Markdown
|
||||
|
||||
在深入 Spec Coding 之前，先理解 Claude Code 的底层哲学：**万物皆 Markdown**。
|
||||
|
||||
Claude Code 的设计哲学中，所有过程记载、信息传递、甚至与模型的对话，都可以是 Markdown：
|
||||
|
||||
- **CLAUDE.md**：项目规范的 Markdown 文档
|
||||
- **.claude/rules/**：分层规范的 Markdown 文件集合
|
||||
- **specs/**：功能需求的 Markdown 描述
|
||||
- **对话历史**：Claude Code 的对话记录本身就是 Markdown 格式
|
||||
- **AGENTS.md**：Agent 行为规范的 Markdown 指令
|
||||
|
||||
这正是 Spec Coding 的内核：**规范本身就是代码**。当你用 Markdown 写下需求、设计、验收标准时，你已经在写"代码"了——AI 会读取这些 Markdown，然后生成真正的代码实现。
|
||||
|
||||
Josh Beckman 对 Grove 演讲的总结一针见血：
|
||||
|
||||
> "Software engineering (and lawmaking and legal review) is specification repair."
|
||||
> 软件工程（以及立法和法律审查）的本质是规范修复。
|
||||
|
||||
在 Claude Code 中，这个"规范修复"的过程就是：**修改 Markdown → AI 读取 Markdown → 生成/修改代码 → 验证结果**。整个过程都是 Markdown 驱动的。
|
||||
|
||||
---
|
||||
|
||||
## 1. Sean Grove 的 "The New Code"：一场改变思维的演讲
|
||||
|
||||
2025 年，OpenAI 研究员 **Sean Grove** 在 AI Engineer World's Fair 上发表了一场题为 **"The New Code"** 的演讲，震动了整个开发者社区。他提出了一个颠覆性的观点：**70 年来我们一直在写代码来解决问题，但代码只是意图的有损投影——规范才是真正的"新代码"**。
|
||||
|
||||
这场演讲催生了一种新的开发范式：**Spec Coding**（规范编程）——以规范文档而非代码作为开发的核心产物，让 AI 根据规范生成代码。
|
||||
|
||||
本文将从 Grove 的演讲出发，带你理解 Spec Coding 的核心思想，回顾 Vibe Coding 的局限，并结合 Claude Code 的实践，展示如何在真实开发中运用这种方法论。
|
||||
|
||||
::: info 📚 你将学到
|
||||
|
||||
1. 理解 Sean Grove "The New Code" 演讲的关键思想
|
||||
2. 掌握 Spec Coding 的核心理念和方法论
|
||||
3. 认识 Vibe Coding 的价值与天花板
|
||||
4. 学会在 Claude Code 中实践 Spec Coding 工作流
|
||||
5. 掌握从 Vibe Coding 到 Spec Coding 的渐进式过渡策略
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 1. Sean Grove 的 "The New Code"：一场改变思维的演讲
|
||||
|
||||
2025 年，OpenAI 研究员 Sean Grove 在 AI Engineer World's Fair 上发表了题为 **"The New Code"** 的演讲。这场演讲被广泛认为是 Spec Coding 运动的思想源头。
|
||||
|
||||
Grove 此前创办了 OneGraph（一个 GraphQL 开发工具公司，后被 Netlify 收购），目前在 OpenAI 从事 alignment reasoning 工作——帮助将高层意图转化为可执行的规范和评估标准。
|
||||
|
||||
### 1.1 核心论点：代码是意图的有损投影
|
||||
|
||||
Grove 演讲的核心概念可以用一句话概括：
|
||||
|
||||
> **Code is a lossy projection of intent.**
|
||||
> 代码是意图的有损投影。
|
||||
|
||||
什么意思？当你脑子里有一个想法，把它变成代码的过程中，大量的上下文信息会丢失——**为什么**要这样做、**权衡了哪些方案**、**考虑了什么约束**。最终的代码只保留了"怎么做"，却丢掉了"为什么这样做"。
|
||||
|
||||
这就像把一本书压缩成一条推文——信息量大幅缩减，原始意图被严重损耗。
|
||||
|
||||
### 1.2 编程的本质是沟通
|
||||
|
||||
Grove 提出了一个看似简单却深刻的观点：
|
||||
|
||||
> "If you can communicate effectively, you can program."
|
||||
> 如果你能有效沟通，你就能编程。
|
||||
|
||||
他认为，实际编码工作只占开发的 **10-20%**，剩下的 80% 是围绕需求和目标的**结构化沟通**——理解用户要什么、和团队对齐方案、定义验收标准、处理边界情况。
|
||||
|
||||
这意味着编程能力的核心不是掌握某种语言的语法，而是**把模糊的意图转化为精确描述的能力**。
|
||||
|
||||
### 1.3 写规范的人就是程序员
|
||||
|
||||
这是 Grove 最具颠覆性的观点：
|
||||
|
||||
> "Whoever writes the spec — be it a PM, a lawmaker, an engineer, a marketer — is now the programmer."
|
||||
> 无论是产品经理、律师、工程师还是市场人员，写规范的人就是程序员。
|
||||
|
||||
随着 AI 越来越擅长把规范转化为代码，**真正的编程工作**从"写代码"变成了"写规范"。谁能最精确地表达意图，谁就是最有价值的"程序员"。
|
||||
|
||||
### 1.4 规范拥有类似代码的工具链
|
||||
|
||||
Grove 指出，规范可以像代码一样拥有完整的工具链：
|
||||
|
||||
> "Specs actually give us a very similar toolchain, but it's targeted at intentions rather than syntax."
|
||||
|
||||
- **组合**：规范可以模块化组合，就像代码模块
|
||||
- **测试**：规范可以嵌入单元测试，验证行为是否符合预期
|
||||
- **Lint 检查**：可以检测规范中的模糊语言，就像代码 linter 检测语法问题
|
||||
- **一致性验证**：跨部门的规范可以做一致性检查，类似类型检查器
|
||||
|
||||
### 1.5 OpenAI Model Spec：活的证明
|
||||
|
||||
Grove 用 OpenAI 自己的 **Model Spec** 文档作为实证。
|
||||
|
||||
当 OpenAI 发现模型存在 sycophancy（过度迎合用户）问题时，他们没有重新训练模型，而是**修改了规范文档**。改动自动传播到整个系统，问题得到修正。
|
||||
|
||||
这证明了一个关键点：**规范本身可以作为"可执行代码"发挥作用**。修改规范就等于修改行为，不需要碰一行传统代码。
|
||||
|
||||
Josh Beckman 对 Grove 演讲的总结一针见血：
|
||||
|
||||
> "Software engineering (and lawmaking and legal review) is specification repair."
|
||||
> 软件工程（以及立法和法律审查）的本质是规范修复。
|
||||
|
||||
---
|
||||
|
||||
## 2. Spec Coding：规范即代码
|
||||
|
||||
### 2.1 什么是 Spec Coding
|
||||
|
||||
Spec Coding（规范编程），也叫 Spec-Driven Development（SDD），是一种以**规范文档作为开发核心产物**的方法论。
|
||||
|
||||
核心思路：**先写清楚规范，再让 AI 根据规范生成代码。规范是 source of truth，代码只是规范的实现产物。**
|
||||
|
||||
Robert C. Martin 在《Clean Code》中的经典论断在 AI 时代被重新激活：
|
||||
|
||||
> "Specifying requirements so precisely that a machine can execute them is programming."
|
||||
> 把需求描述得足够精确以至于机器能执行它——这就是编程。
|
||||
|
||||
### 2.2 Vibe Coding vs Spec Coding 对比
|
||||
|
||||
| 维度 | Vibe Coding | Spec Coding |
|
||||
|------|------------|-------------|
|
||||
| **方式** | 即兴 prompt，逐条迭代 | 先写完整规范，再生成代码 |
|
||||
| **适用场景** | 原型、hackathon、探索 | 生产系统、团队协作、企业级 |
|
||||
| **代码质量** | 快但脆弱 | 结构化、可测试、可审计 |
|
||||
| **首次通过率** | 不稳定 | 目标 95%+ |
|
||||
| **可复用性** | 一次性 prompt | 规范可跨项目复用 |
|
||||
| **安全性** | 容易遗漏 | 从规范层面内建 |
|
||||
| **文档** | 无或滞后 | 规范即文档，自维护 |
|
||||
| **团队协作** | 依赖个人 prompt 技巧 | 共享规范，统一标准 |
|
||||
|
||||
两者并非对立。Brad Jolicoeur 指出：
|
||||
|
||||
> "Clever engineers will even use vibe coding as a first step to generate the initial draft of a specification."
|
||||
> 聪明的工程师会用 Vibe Coding 作为第一步，生成规范的初始草稿。
|
||||
|
||||
### 2.3 Spec Coding 的三层规范结构
|
||||
|
||||
Red Hat 的工程师总结了一个实用的三层规范模型：
|
||||
|
||||
**第一层：功能规范（What）**
|
||||
|
||||
用自然语言描述期望结果，回答"做什么"：
|
||||
|
||||
```markdown
|
||||
## 用户认证功能
|
||||
|
||||
### 用户故事
|
||||
- 作为新用户，我希望能通过邮箱注册账号
|
||||
- 作为已注册用户，我希望能用邮箱和密码登录
|
||||
- 作为忘记密码的用户，我希望能通过邮件重置密码
|
||||
|
||||
### 验收标准
|
||||
- 注册时验证邮箱格式和密码强度
|
||||
- 登录失败 5 次后锁定账号 15 分钟
|
||||
- 密码重置链接 30 分钟内有效
|
||||
```
|
||||
|
||||
**第二层：语言无关规范（How - 架构层）**
|
||||
|
||||
定义数据结构、架构模式、安全要求：
|
||||
|
||||
```markdown
|
||||
## 技术设计
|
||||
|
||||
### 数据模型
|
||||
- users 表：id, email, password_hash, created_at, locked_until
|
||||
- sessions 表：id, user_id, token, expires_at
|
||||
|
||||
### API 设计
|
||||
- POST /api/auth/register → 201 Created
|
||||
- POST /api/auth/login → 200 OK + JWT
|
||||
- POST /api/auth/reset-password → 202 Accepted
|
||||
|
||||
### 安全要求
|
||||
- 密码使用 bcrypt 加密，cost factor ≥ 12
|
||||
- JWT 有效期 15 分钟，refresh token 7 天
|
||||
- 所有端点启用 rate limiting
|
||||
```
|
||||
|
||||
**第三层：语言特定规范（How - 实现层）**
|
||||
|
||||
版本要求、测试框架、文档标准：
|
||||
|
||||
```markdown
|
||||
## 实现约束
|
||||
|
||||
### 技术栈
|
||||
- Runtime: Node.js 20+
|
||||
- Framework: Express 5
|
||||
- ORM: Prisma
|
||||
- Testing: Vitest
|
||||
|
||||
### 代码规范
|
||||
- 使用 TypeScript strict mode
|
||||
- 错误处理使用自定义 AppError 类
|
||||
- 所有 API 端点需要 JSDoc 注释
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 在 Claude Code 中实践 Spec Coding
|
||||
|
||||
理解了理论，接下来看如何在 Claude Code 中落地。Claude Code 的设计哲学天然契合 Spec Coding——它的 `CLAUDE.md`、Rules 目录、`/plan` 命令，本质上都是在做"规范驱动"。
|
||||
|
||||
OpenAI 自己用 Codex 构建项目时，也采用了类似的方式：用 `AGENTS.md` 文件作为规范来引导 AI agent。他们的核心经验是——**当 agent 遇到困难时，把它当作信号：找出缺少什么（工具、护栏、文档），然后补充到仓库中**。这和 Spec Coding 的理念完全一致：规范是活的，需要持续演进。
|
||||
|
||||
Augment Code 的研究也印证了这一点：**可执行规范之所以保持准确，是因为 AI agent 直接从规范生成代码，形成了一个强制函数——过时的规范会产生坏掉的实现**。这意味着规范不会像传统文档那样腐烂。
|
||||
|
||||
### 3.1 第一步：用 CLAUDE.md 建立项目规范
|
||||
|
||||
`CLAUDE.md` 就是你项目的"活规范"。每次 Claude Code 启动时都会读取它，相当于给 AI 一份持久的项目说明书。
|
||||
|
||||
在前面的 [Claude Code 快速上手核心指南](../basics/) 中，我们学过如何创建 `CLAUDE.md`。在 Spec Coding 的语境下，它的角色更加重要——**它不只是配置文件，而是项目规范的入口**。
|
||||
|
||||
LogRocket 的工程师强调：**坚实的上下文对于 AI agent 至关重要，它能防止幻觉和低效**。没有规范的 AI agent 可能会对项目做出大范围的、不受控的修改。`CLAUDE.md` 就是提供这个"坚实上下文"的第一道防线。
|
||||
|
||||
```markdown
|
||||
# 电商项目规范
|
||||
|
||||
## 项目定位
|
||||
面向中小商家的 SaaS 电商平台，支持多店铺、多支付渠道。
|
||||
|
||||
## 架构决策
|
||||
- 前后端分离，API-first 设计
|
||||
- 后端微服务架构，服务间通过消息队列通信
|
||||
- 数据库读写分离
|
||||
|
||||
## 核心约束
|
||||
- 所有金额使用整数（分）存储，避免浮点精度问题
|
||||
- 订单状态机严格遵循：待支付 → 已支付 → 已发货 → 已完成
|
||||
- 支付相关接口必须幂等
|
||||
```
|
||||
|
||||
Aviator 的团队总结了规范应该捕获的关键信息——这也是你写 `CLAUDE.md` 时应该覆盖的：
|
||||
|
||||
- 输入/输出格式和数据类型
|
||||
- 业务规则和边界情况
|
||||
- 系统依赖和约束
|
||||
- 性能和扩展要求
|
||||
- 错误处理和安全需求
|
||||
|
||||
### 3.2 第二步：用 Rules 目录管理分层规范
|
||||
|
||||
当项目变大，单个 `CLAUDE.md` 不够用。这时候用 `.claude/rules/` 目录来组织分层规范。
|
||||
|
||||
这正是 Augment Code 所说的"可执行规范"理念：**规范不是静态文档，而是 AI agent 直接消费的活的指令**。当你把规范拆分到 Rules 目录中，每个规范文件只在相关文件被编辑时加载，既节省 token 又保证精准。
|
||||
|
||||
Tessl 的工程师发现，将需求分解为结构化文档——PRD 定义"做什么和为什么"，技术规范定义"怎么做"——能有效防止 AI 在长对话中"混淆累积"，显著提升输出一致性。
|
||||
|
||||
```
|
||||
.claude/rules/
|
||||
├── 00-architecture.md # 架构规范（全局）
|
||||
├── 01-security.md # 安全规范（全局）
|
||||
├── 10-api-design.md # API 设计规范
|
||||
├── 11-frontend-patterns.md # 前端模式规范
|
||||
├── 12-database.md # 数据库规范
|
||||
└── 20-testing.md # 测试规范
|
||||
```
|
||||
|
||||
每个规范文件可以通过 frontmatter 指定适用范围：
|
||||
|
||||
```markdown
|
||||
---
|
||||
globs:
|
||||
- "src/api/**/*.ts"
|
||||
- "src/services/**/*.ts"
|
||||
---
|
||||
|
||||
# API 设计规范
|
||||
|
||||
## 路由设计
|
||||
- RESTful 风格，使用名词复数：/api/v1/orders
|
||||
- 嵌套资源最多两层：/api/v1/users/123/orders
|
||||
|
||||
## 响应格式
|
||||
- 成功：{ data, pagination? }
|
||||
- 错误：{ error: { code, message, details? } }
|
||||
|
||||
## 必须遵守
|
||||
- 所有写操作需要认证
|
||||
- 列表接口必须支持分页
|
||||
- 敏感操作记录审计日志
|
||||
```
|
||||
|
||||
这样，当 Claude Code 编辑 API 相关文件时，会自动加载这份规范，确保生成的代码符合标准。
|
||||
|
||||
### 3.3 第三步：用 /plan 实现 Specify → Plan → Tasks → Implement
|
||||
|
||||
Spec Coding 的标准工作流是四阶段循环。GitHub Spec Kit 将其标准化为 Specify → Plan → Tasks → Implement，而 Claude Code 的 `/plan` 命令天然支持这个流程。
|
||||
|
||||
SpecThis 的团队强调了一个关键原则：**在 agent 运行之前定义边界——在代码变更之前就知道什么应该改变**。这正是 `/plan` 的价值所在。
|
||||
|
||||
**阶段一：Specify（定义规范）**
|
||||
|
||||
先写清楚要做什么，不急着写代码：
|
||||
|
||||
```
|
||||
/plan
|
||||
我需要实现订单退款功能，规范如下：
|
||||
|
||||
功能需求：
|
||||
- 用户可以在发货前申请全额退款
|
||||
- 发货后 7 天内可以申请退货退款
|
||||
- 退款需要管理员审批
|
||||
|
||||
验收标准：
|
||||
- 退款金额不能超过订单实付金额
|
||||
- 退款状态机：申请中 → 审批通过 → 退款中 → 已退款
|
||||
- 退款完成后恢复库存
|
||||
- 全程记录操作日志
|
||||
```
|
||||
|
||||
**阶段二：Plan（技术规划）**
|
||||
|
||||
Claude 会基于你的规范生成技术方案：
|
||||
|
||||
```
|
||||
📋 退款功能实施计划
|
||||
|
||||
1. 数据模型设计
|
||||
- 创建 refunds 表
|
||||
- 添加订单状态机的退款相关状态
|
||||
|
||||
2. API 设计
|
||||
- POST /api/orders/:id/refund - 申请退款
|
||||
- PUT /api/refunds/:id/approve - 审批退款
|
||||
- GET /api/refunds - 退款列表
|
||||
|
||||
3. 业务逻辑
|
||||
- 退款资格校验
|
||||
- 退款金额计算
|
||||
- 库存恢复逻辑
|
||||
|
||||
4. 集成
|
||||
- 对接支付渠道退款接口
|
||||
- 发送退款通知
|
||||
```
|
||||
|
||||
**阶段三：Tasks（任务拆解）**
|
||||
|
||||
将计划拆分为可独立执行的小任务，每个任务有明确的完成标准。
|
||||
|
||||
**阶段四：Implement（逐步实现）**
|
||||
|
||||
按任务逐个实现，每完成一个就验证一次。
|
||||
|
||||
### 3.4 实战案例：用 Spec Coding 构建用户通知系统
|
||||
|
||||
让我们通过一个完整的例子，对比 Vibe Coding 和 Spec Coding 的差异。Orchestrator.dev 的数据显示，2025 Stack Overflow 调查中 84% 的开发者使用或计划使用 AI 工具，但只有 22% 对结果满意，46% 认为准确性有问题。Spec Coding 正是解决这个满意度鸿沟的关键。
|
||||
|
||||
**Vibe Coding 方式：**
|
||||
|
||||
```
|
||||
你：做一个通知功能
|
||||
AI：[直接开始写代码，生成了一个简单的通知列表]
|
||||
|
||||
你：要支持已读未读
|
||||
AI：[修改代码，加了个 read 字段]
|
||||
|
||||
你：还要支持不同类型的通知
|
||||
AI：[又改，加了 type 字段]
|
||||
|
||||
你：要能推送到手机
|
||||
AI：[大改一通，之前的结构不太适配了...]
|
||||
```
|
||||
|
||||
结果：改了 4 轮，架构被反复推翻，代码越来越乱。
|
||||
|
||||
**Spec Coding 方式：**
|
||||
|
||||
先写规范文档 `specs/notification.md`：
|
||||
|
||||
```markdown
|
||||
# 用户通知系统规范
|
||||
|
||||
## 功能需求
|
||||
1. 支持站内通知、邮件通知、推送通知三种渠道
|
||||
2. 通知类型：系统公告、订单状态、促销活动、安全提醒
|
||||
3. 用户可以按渠道和类型配置通知偏好
|
||||
4. 支持已读/未读状态，支持批量标记已读
|
||||
|
||||
## 数据模型
|
||||
- notifications 表：id, user_id, type, channel, title, content,
|
||||
is_read, created_at
|
||||
- notification_preferences 表：user_id, type, channel, enabled
|
||||
|
||||
## API 设计
|
||||
- GET /api/notifications?type=&is_read= - 获取通知列表（分页）
|
||||
- PUT /api/notifications/:id/read - 标记已读
|
||||
- PUT /api/notifications/read-all - 全部标记已读
|
||||
- GET /api/notification-preferences - 获取偏好设置
|
||||
- PUT /api/notification-preferences - 更新偏好设置
|
||||
|
||||
## 验收标准
|
||||
- 未读通知数实时更新
|
||||
- 通知列表支持无限滚动
|
||||
- 推送通知延迟 < 3 秒
|
||||
- 偏好设置变更立即生效
|
||||
```
|
||||
|
||||
然后在 Claude Code 中：
|
||||
|
||||
```
|
||||
@specs/notification.md
|
||||
按照这份规范实现用户通知系统。
|
||||
先从数据模型开始，然后实现 API，最后做前端组件。
|
||||
每完成一个模块暂停一下，我确认后再继续。
|
||||
```
|
||||
|
||||
结果：一次到位，架构清晰，不需要反复推翻重来。
|
||||
|
||||
### 3.5 结合 Superpowers 强化 Spec Coding
|
||||
|
||||
在前面的 [Superpowers 工程级开发](../superpowers/) 章节中，我们学过 Superpowers 的技能体系。Spec Coding 和 Superpowers 是天然的搭档：
|
||||
|
||||
| Spec Coding 阶段 | 对应 Superpowers 技能 |
|
||||
|------------------|---------------------|
|
||||
| 定义规范 | `brainstorming` — 苏格拉底式提问澄清需求 |
|
||||
| 技术规划 | `writing-plans` — 将规范拆解为小任务 |
|
||||
| 逐步实现 | `test-driven-development` — TDD 红绿重构 |
|
||||
| 质量验证 | `code-review` + `verification-before-completion` |
|
||||
|
||||
**组合使用示例：**
|
||||
|
||||
```
|
||||
@specs/notification.md
|
||||
用 TDD 方式按照这份规范实现通知系统，
|
||||
完成后帮我做代码审查
|
||||
```
|
||||
|
||||
这条指令同时触发了 Spec Coding 工作流和 Superpowers 的 TDD + Code Review 技能，形成完整的工程级开发流程。
|
||||
|
||||
### 3.6 规范的版本控制与持续演进
|
||||
|
||||
The Vibe Coding Substack 提出了一个重要观点：**Specs are now code**。既然规范是代码，就应该像代码一样管理：
|
||||
|
||||
- **版本控制**：规范文件放在 Git 仓库中，和代码一起提交
|
||||
- **变更追踪**：每次修改规范都有 commit 记录，知道谁改了什么、为什么改
|
||||
- **Code Review**：规范的修改也需要 PR 审查，确保团队对齐
|
||||
- **CI 集成**：规范变更触发自动化测试，验证实现是否仍然符合规范
|
||||
|
||||
在 Claude Code 中，这意味着你的 `CLAUDE.md`、`.claude/rules/` 和 `specs/` 目录都应该纳入版本控制。Robomotion 的经验是：**规范和实现一起版本化，防止漂移，保持可审计性**。
|
||||
|
||||
OpenAI 的 Harness Engineering 实践也验证了这一点：他们的 `AGENTS.md` 文件本身就是由 Codex 编写的，并且随着项目演进持续更新。当 agent 遇到困难时，修复方案不是改代码，而是**让 Codex 自己更新规范**——形成规范的自我修复循环。
|
||||
|
||||
---
|
||||
|
||||
## 4. 混合策略：从 Vibe 到 Spec 的渐进式过渡
|
||||
|
||||
行业共识并非"抛弃 Vibe Coding"，而是**根据场景选择合适的方式**。
|
||||
|
||||
### 4.1 什么时候用 Vibe Coding
|
||||
|
||||
- 验证一个想法是否可行（30 分钟内的原型）
|
||||
- 探索不熟悉的技术或框架
|
||||
- Hackathon 或内部 demo
|
||||
- 一次性脚本或工具
|
||||
|
||||
### 4.2 什么时候用 Spec Coding
|
||||
|
||||
- 生产级功能开发
|
||||
- 多人协作的项目
|
||||
- 需要长期维护的代码
|
||||
- 涉及安全、支付、数据等敏感领域
|
||||
- API 设计和系统集成
|
||||
|
||||
### 4.3 推荐的渐进式工作流
|
||||
|
||||
**阶段一：Vibe 探索**
|
||||
|
||||
用 Vibe Coding 快速验证想法，不写规范，不管代码质量：
|
||||
|
||||
```
|
||||
做一个简单的通知弹窗，看看效果
|
||||
```
|
||||
|
||||
**阶段二：提炼规范**
|
||||
|
||||
验证可行后，把探索中的发现整理成规范。你甚至可以让 AI 帮你：
|
||||
|
||||
```
|
||||
基于我们刚才做的通知功能原型，
|
||||
帮我整理一份正式的功能规范文档，
|
||||
包括数据模型、API 设计和验收标准
|
||||
```
|
||||
|
||||
**阶段三：Spec 重建**
|
||||
|
||||
基于规范，用 Spec Coding 方式重新实现生产级版本：
|
||||
|
||||
```
|
||||
@specs/notification.md
|
||||
按照这份规范从零实现，不要参考之前的原型代码
|
||||
```
|
||||
|
||||
这个流程的好处是：**用 Vibe Coding 的速度验证方向，用 Spec Coding 的质量交付产品**。
|
||||
|
||||
Robomotion 的总结很到位：
|
||||
|
||||
> "The spec is the source of truth. The AI generated output is the draft implementation. Validation is not optional."
|
||||
> 规范是唯一的真相来源。AI 生成的代码只是草稿实现。验证不是可选的。
|
||||
|
||||
---
|
||||
|
||||
## 5. 常见问题
|
||||
|
||||
### Q1：Spec Coding 会不会太慢了？
|
||||
|
||||
写规范确实需要前期投入。但 Greg Ceccarelli 的团队用 Spec Coding 方式，**3 个人在 4 周内交付了一个完整的 macOS 产品**——这在传统开发中几乎不可能。
|
||||
|
||||
前期写规范的时间，会在后期通过减少返工、减少 bug、减少沟通成本来回收。
|
||||
|
||||
### Q2：规范写多详细才够？
|
||||
|
||||
Robomotion 的建议是：**一份高质量的规范可以只有一页**。关键是回答 8 个问题：
|
||||
|
||||
1. 我们在自动化什么？
|
||||
2. 输入是什么？
|
||||
3. 输出是什么？
|
||||
4. 约束条件是什么？
|
||||
5. 失败模式有哪些？
|
||||
6. 安全要求是什么？
|
||||
7. 性能要求是什么？
|
||||
8. 什么测试能证明它工作？
|
||||
|
||||
### Q3：AI 只做规范说的事，遗漏了"显而易见"的功能怎么办？
|
||||
|
||||
这确实是 Spec Coding 的一个局限。GitHub Spec Kit 的用户反馈：AI 会"exactly and only"做规范里写的事。
|
||||
|
||||
解决方法：在规范中加一个"非功能性需求"部分，列出通用期望（错误处理、日志、可访问性等）。或者在 `CLAUDE.md` 中设置全局规则。
|
||||
|
||||
### Q4：小项目也需要 Spec Coding 吗？
|
||||
|
||||
不需要。Spec Coding 适合：
|
||||
- 生产级项目
|
||||
- 多人协作项目
|
||||
- 需要长期维护的项目
|
||||
|
||||
对于快速原型、一次性脚本、学习实验，Vibe Coding 更合适。
|
||||
|
||||
### Q5：怎么让团队接受 Spec Coding？
|
||||
|
||||
从一个小功能开始试点。让团队看到 Spec Coding 减少返工、提高首次通过率的效果。Stack Overflow 2025 调查显示，84% 的开发者使用或计划使用 AI 工具，但只有 22% 对结果满意——Spec Coding 正是提升满意度的关键。
|
||||
|
||||
---
|
||||
|
||||
## 6. 总结
|
||||
|
||||
从 Vibe Coding 到 Spec Coding，不是一次革命，而是一次进化。
|
||||
|
||||
Sean Grove 在 "The New Code" 中说得很清楚：**70 年来我们一直在写代码来解决问题，现在应该写规范来生成代码**。代码是意图的有损投影，而规范才能完整地捕获意图、上下文和约束。
|
||||
|
||||
对于使用 Claude Code 的开发者来说，这个转变其实已经在发生：
|
||||
|
||||
- 你写的 `CLAUDE.md` 就是项目规范
|
||||
- 你配置的 Rules 目录就是分层规范
|
||||
- 你用 `/plan` 做的规划就是 Specify → Plan → Tasks 流程
|
||||
- 你结合 Superpowers 的 TDD 和 Code Review 就是完整的 Spec Coding 工作流
|
||||
|
||||
**关键要点：**
|
||||
|
||||
- Vibe Coding 适合探索和原型，Spec Coding 适合生产和协作
|
||||
- 规范是 source of truth，代码是规范的实现产物
|
||||
- 写规范的能力 = 编程能力，沟通能力 > 语法能力
|
||||
- 从小处开始：先把 `CLAUDE.md` 写好，就已经迈出了 Spec Coding 的第一步
|
||||
|
||||
::: tip 💡 下一步
|
||||
在下一章节中，我们将学习如何使用 Claude Code 的 Agent Teams 功能，让多个 AI 实例像真正的开发团队一样协同工作。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 参考资料
|
||||
|
||||
### Sean Grove "The New Code" 演讲相关
|
||||
|
||||
- [Code is just a lossy projection of intent — The Decoder](https://the-decoder.com/code-is-just-a-lossy-projection-of-intent-according-to-openai-researcher-sean-grove/)
|
||||
- [The End of Coding? How Specifications Are Becoming the New Source Code — Implicator](https://www.implicator.ai/the-end-of-coding-how-specifications-are-becoming-the-new-source-code/)
|
||||
- [OpenAI: Intent, Not Code, Drives Future Software Development — AI Tech Suite](https://www.aitechsuite.com/ai-news/openai-intent-not-code-drives-future-software-development)
|
||||
- [Note on The New Code — Josh Beckman](https://www.joshbeckman.org/notes/914234100)
|
||||
- [The New Code 演讲完整文字稿](https://lawwu.github.io/transcripts/8rABwKRsec4.html)
|
||||
|
||||
### Spec Coding 方法论
|
||||
|
||||
- [How spec-driven development improves AI coding quality — Red Hat](https://developers.redhat.com/articles/2025/10/22/how-spec-driven-development-improves-ai-coding-quality)
|
||||
- [Spec-Driven Development with AI: Complete 2025 Guide — Dplooy](https://www.dplooy.com/blog/spec-driven-development-with-ai-complete-2025-guide)
|
||||
- [Spec-Driven Development: Building Production-Ready Software with AI — Orchestrator.dev](https://orchestrator.dev/blog/2025-12-16-spec_driven_dev_article)
|
||||
- [Agents Code but the Problem of Clear Specification Remains — Greg Ceccarelli](https://www.gregceccarelli.com/writing/beyond-code-centric)
|
||||
|
||||
### Vibe Coding vs Spec Coding
|
||||
|
||||
- [Vibe Coding vs Spec Driven — Cosmo Edge](https://cosmo-edge.com/vibe-coding-vs-spec-driven-ai-development/)
|
||||
- [Master AI in Software Engineering: Vibe vs. Spec Coding — Brad Jolicoeur](https://bradjolicoeur.com/article/ai-software-engineering-vibe-spec-prompting)
|
||||
- [From Vibe Coding to Spec-Driven Development — Tessl](https://tessl.io/blog/from-vibe-coding-to-spec-driven-development/)
|
||||
- [Spec first approach for enterprise — Robomotion](https://robomotion.io/blog/spec-first-approach-the-way-to-adapt-vibe-coding-for-enterprise-work)
|
||||
|
||||
### 工具与实践
|
||||
|
||||
- [GitHub Spec Kit vs Vibe Coding — Ossels](https://ossels.ai/github-spec-kit-spec-driven-development/)
|
||||
- [A spec-first workflow for agentic AI — LogRocket](https://blog.logrocket.com/spec-first-workflow-agentic-ai/)
|
||||
- [Specs Are Now Code — The Vibe Coding Substack](https://thevibecoding.substack.com/p/specs-are-now-code)
|
||||
- [Harness Engineering — Martin Fowler](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
|
||||
- [Spec-Driven Development & AI Agents Explained — Augment Code](https://www.augmentcode.com/guides/spec-driven-development-ai-agents-explained)
|
||||
- [Spec-Driven Development: The Key to Scalable AI Agents — Aviator](https://www.aviator.co/blog/spec-driven-development/)
|
||||
|
||||
Reference in New Issue
Block a user