delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): add new documentation for mobile development, spec coding and claude agent sdk

Browse Source 
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
2026-03-02 12:42:07 +08:00
parent c6c0c3950d
commit b99d4af698
5 changed files with 2293 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vitepress/config.mjs
+26
View File
@@ -398,6 +398,20 @@ const stage3SidebarEn = [
{ {
text: 'Claude Code 工作流最佳实践', text: 'Claude Code 工作流最佳实践',
link: '/zh-cn/stage-3/core-skills/workflow/' link: '/zh-cn/stage-3/core-skills/workflow/'
},
{
text: 'Claude Code 手机远程开发',
link: '/zh-cn/stage-3/core-skills/mobile-development/'
},
{
text: 'Claude Agent SDK 完全指南',
link: '/zh-cn/stage-3/core-skills/claude-agent-sdk/',
items: [
{
text: 'Spec Coding：规范驱动开发',
link: '/zh-cn/stage-3/core-skills/claude-agent-sdk/spec-coding'
}
]
} }
] ]
}, },
@@ -1245,6 +1259,18 @@ export default defineConfig({
{ {
text: 'Claude Code 工作流最佳实践', text: 'Claude Code 工作流最佳实践',
link: '/zh-cn/stage-3/core-skills/workflow/' link: '/zh-cn/stage-3/core-skills/workflow/'
},
{
text: 'Claude Code 手机远程开发',
link: '/zh-cn/stage-3/core-skills/mobile-development/'
},
{
text: 'Claude Agent SDK 完全指南',
link: '/zh-cn/stage-3/core-skills/claude-agent-sdk/'
},
{
text: '从 Vibe Coding 到 Spec Coding',
link: '/zh-cn/stage-3/core-skills/spec-coding/'
} }
] ]
}, },
docs/zh-cn/stage-3/core-skills/basics/index.md
+61
View File
@@ -569,6 +569,67 @@ Token 使用：45,230 / 200,000 (22.6%)
2. **优化 .claudeignore**：将不相关的文件（如 node_modules、构建产物）加入忽略列表 2. **优化 .claudeignore**：将不相关的文件（如 node_modules、构建产物）加入忽略列表
3. **决定何时压缩**：当使用率超过 70% 时，考虑使用 `/compact` 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` 切换，保持上下文清晰
--- ---
## 核心配置 ## 核心配置
docs/zh-cn/stage-3/core-skills/claude-agent-sdk/index.md
+689
View File
@@ -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 双轨教程
docs/zh-cn/stage-3/core-skills/mobile-development/index.md
+904
View File
@@ -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 客户端
docs/zh-cn/stage-3/core-skills/spec-coding/index.md
+613
View File
@@ -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/)