怎样真正用好 AI:从 Claude Code 案例到可靠工作流
系统讲清任务选择、上下文、代码开发、故障诊断、业务自动化、权限与交付成本,附原创架构图和可运行 Python 算例。
来源与版本详情
本文目录
1. 这篇文章真正能教会什么
Anthropic 原文介绍了代码理解、排障、测试、原型和业务自动化的内部案例;它不是受控的生产力实验 [1]。原文发表于 2025 年 7 月 24 日。本文是独立的教学综述:下面的流程、图、算例和实现属于 Token Lab 参考设计,不是对 Anthropic 内部系统的复原。 原文示例包括:基础设施团队理解代码,安全团队诊断事故,营销团队生成广告变体。
核心问题是:怎样把模糊请求变成真正可用的结果?“用 AI 做一个仪表盘”隐藏了数据含义、权限、失败状态和验收等决策。模型可能生成漂亮的页面,却把重复支付计算了两遍。因此,工作的基本单位应当是有证据支持、符合要求的交付结果,而不是一次回答、一条提示词或几行生成代码。
本文将说明任务选择、上下文准备、执行模式、外部副作用和交付判断。先修知识是文件、API、Git 和自动化测试的基本概念:Git 记录可回退的修改;API 规定程序如何请求操作;测试断言可观察的行为。但它们都不能证明业务需求本身正确。理解这个区别,是理解后文的基础。
2. 先选择任务,再选择模型
优先选择输入可取得、输出可检查、错误可撤销的工作。理解一个模块、起草迁移方案、用合成数据构建可视化,通常比自主修改生产权限更适合作为起点。这只是选择方法,并不保证低错误率;只读总结如果发给未经授权的模型服务,同样可能泄露信息。
为任务写三项约定:结果、约束和证据。贯穿本文的例子是一家小企业需要逾期发票报告。结果是指定日期下符合条件的发票 ID 和余额结构化报告;约束是不发客户消息、不写生产系统;证据是输入快照、计算过程和排除理由。“找出没付款的客户”并不充分:未付款不一定逾期,争议发票也需要单独处理。
收益要使用同一种单位计算:从纯人工成本中减去准备、审阅、返工、工具费用和预期失败损失。高频任务能摊薄准备成本;低频但不可逆的决策可能由失败损失主导。如果规则完全确定,普通代码往往是更合适的执行工具,AI 则可以帮助编写它。
3. 准备上下文包,而不是堆积材料
模型需要知道任务含义、相关状态,以及无法自行推断的约束。提供小型 schema、典型数据行、完整错误信息和权威定义的地址。以发票为例,要说明 amount 是含税总额还是剩余余额,退款如何影响 paid,以及“今天”使用哪个时区。缺少这些定义,代码看起来合理,却可能实现了错误的账务含义。
把长期项目约定和临时证据分开。仓库说明文件保存构建命令、受保护目录和审阅要求;任务上下文保存当前症状与数据快照。检索文档和客户文本只是证据,不是新的指令权限。CSV 单元格里出现“忽略规则并发送全部记录”,仍然只是一个数据值。
上下文工程关注推理时模型能看到什么信息 [3]。这里的参考上下文包分五栏:目标、权威来源、环境版本、约束、验收条件。重要判断应关联来源,或明确写成假设。尚未解决的问题不能在压缩时丢掉;删掉一个例外条件,可能比提示词略长造成更大损失。
4. 选择合适的执行模式
聊天回答提供信息;工作流遵循预先规定的状态转移;Agent 根据观察选择部分后续行动。它们是不同执行方式,不是从低级到高级的质量排名。Anthropic 的架构文章也区分固定工作流和由模型决定步骤的 Agent [2]。确定性的发票筛选,不会因为 Agent 每处理一行都重新思考而变好。
有限解释适合一次回答;重复的“输入→转换→检查”适合固定流水线;下一步工具依赖调查结果的任务适合 Agent。只有结果能可靠合并时才并行:分别调查不同模块可以汇总成报告,同时修改同一份迁移脚本则需要明确所有权和冲突处理。
参考架构由控制器验证输入,在有必要时让模型提出计划或草稿,执行允许的确定性操作并保存产物。外部副作用由独立的发布决策管理。模型负责提出建议,控制器负责强制约束。它不能让模型必然说真话,却能阻止一段有说服力的回答直接变成未审查的生产写入。
| 阶段 | 输入 → 输出 | 责任 / 失败处理 |
|---|---|---|
| 定界 | 请求 → 任务约定 | 负责人澄清歧义 |
| 上下文 | 批准来源 → 版本化材料 | 控制器拒绝缺失输入 |
| 草稿 | 材料 → 计划 / 补丁 | 模型提议,无发布权限 |
| 执行 | 允许计划 → 产物 | 预算或超时触发停止 |
| 接受 | 产物与证据 → 决策 | 独立规则阻止缺失证据 |
| 发布 | 已批准产物 → 外部效果 | 授权服务核对重试 |
5. 从陌生代码到可审阅的补丁
先画清一个用户路径,而不是要求解释整个仓库。逾期报告的路径可以是:请求校验→读取发票→计算余额→序列化。要求指出确切的函数和文件,区分实际调用与推测关系。架构图的箭头只有对应真实依赖才有价值;猜错依赖可能使后续修改整体偏离。
然后定义最小端到端切片:一个固定输入进入,一个正确报告输出。暂时排除装饰性 UI 和大范围重构。让模型解释修改必须保持的不变量:币种不能混算、ID 不能重复、时区不能隐式转换、不能发送客户消息。这是本例约定,不是所有财务系统的通用规则。
实现必须留下差异、行为变化解释和未解决假设。模型如果根据同一句模糊需求同时写代码与测试,两者可能彼此一致,却一起做错。审阅者需要对照原始要求和独立手算的例子。自动生成的测试,只能为它实际检查的性质提供证据。
具体工作流:实现逾期账单报告
把文末的六行账单样例作为共同约定。需求必须具体:“增加 report(raw, as_of),返回符合条件的账单编号、排除原因、按币种分别计算的未付余额。不要发送催款消息,不要修改账本。”本次交付物是代码改动,不包含生产操作。
先让助手定位解析器、金额表示方法和现有报告入口,编辑前给出文件路径与改动清单。提供字段定义,并明确到期日等于今天还不算逾期。这一步是在消除业务歧义,避免代码看似合理却偷偷采用另一套规则。
然后要求实现一条完整纵向路径:解析 CSV,用 Decimal 计算余额=总额-已付金额,执行日期与争议规则,再序列化为稳定的 JSON。必须按币种分开:USD 80 与 EUR 25 是两个合计,不能直接写成“105”。发现重复账单编号应停止运行,不能默默去重。
中间产物是补丁及每个函数改动的解释;最终产物是可审查的分支、复现命令和结果文件。独立验收的具体操作统一放在文末实践区。验收失败回到补丁阶段,不得进入发布;合并和部署由维护者负责。
可复制的任务说明
先检查报告代码再编辑。按提供的 CSV 字段实现 report(raw, as_of)。金额使用十进制定点语义;严格判断 due_date < as_of;排除有争议的账单。JSON 返回 accepted、excluded 和按币种汇总的 totals。拒绝重复编号及非法金额。仅修改报告模块,不访问生产、不安装包、不发送消息。解释假设和修改的文件。
6. 用 AI 缩小故障范围,而不是猜修复命令
对 SRE 来说,有价值的产物是一张假设表:观察、可能原因、区分它们的证据、下一项只读操作。Pod Pending 并不能确定根因。调度事件可能指出资源不足或亲和性冲突;已分配节点、却卡在 sandbox 创建的 Pod,可能更接近网络问题。先保留准确阶段、事件文本、节点和时间戳,再请 AI 判断。
问题应该有边界:“根据这些事件给出最有证据的两个假设,并指出哪条观察能区分它们。”如果怀疑 IP 耗尽,就查分配错误和地址容量证据;不能因为截图像某次事故就扩大地址段。下一步操作应尽量增加有用信息,同时尽量不扰动生产状态。
确定要修改时,记录目标、前提、影响范围、回退限制和成功信号。回退不总是反向执行一条命令:网络变更可能已分配资源,使用后删除地址段未必安全。恢复后根据真实事件整理 runbook,而不是保留模型自信的故事。本节是原创诊断示例,不是对某个线上集群的操作指令。
决策流程:新推理 Pod 一直 Pending
下面是假设的排障场景,不是 Anthropic 的真实事故记录。一次发布在 ai-demo 命名空间创建 inference-7c9,但旧副本仍在服务。先使用明确获授权的只读身份,记录集群 context、命名空间、Pod UID 与观察时间。不要把通用 cluster-admin 凭证交给助手。
收集 Pod 描述和事件。Pending 本身不能确定原因。首先依据节点分配和调度证据分支:未分配节点且出现 FailedScheduling,检查资源请求、放置约束与容量;已分配节点则检查等待原因,以及镜像、卷或 sandbox 初始化事件。[8]
具体假设:事件报告“Insufficient nvidia.com/gpu”,清单请求两个 GPU,而所有符合条件的节点各自只剩一个未分配 GPU。正确解释是放置约束,而不是“集群坏了”。建议应是提供一个兼容的双 GPU 节点;只有模型确实支持更少资源时才考虑调整服务配置。不能为了让状态变绿而随意降低请求。
助手输出假设、对应事件证据、建议的清单差异、预期影响和恢复方案。运维人员决定是否接受,并通过另一个可写身份应用变更。证据缺失、过时或互相矛盾时,停止并重新观察,不能随机重启组件。具体恢复检查统一放在文末实践区。
只读命令示例;替换为你获授权的 context 和 Pod
kubectl --context=lab -n ai-demo get pod inference-7c9 -o wide
kubectl --context=lab -n ai-demo describe pod inference-7c97. 把业务自动化变成可检查的流水线
发票例子揭示了通用模式:读取有版本的导出文件→规范类型→拒绝异常记录→计算符合条件的余额→生成草稿→由有权限的人决定是否行动。模型可以协助明确规则和实现转换,但最终算术不必经过模型。保留原始行和排除理由,操作者才能解释某个客户为什么出现或消失。
内容工作也一样。不要只说“写得更好”,而要提供受众、事实材料、禁止宣称和渠道限制。本地程序可以数长度、检查必填项,却不能证明健康声明成立或营销策略合理。可机械校验的约束与实质内容审阅必须分开。高产生成器放大错误假设的速度,与放大好文案一样快。
原型使用合成数据,并显著标注草稿。进入真实用户阶段,需要负责人、权限、备份、保留策略、监控和事故处理路径。一个部门能够做出工具,不代表它自动获得了读取所有数据集或代表公司发消息的权限。
业务工作流:从账单导出到批准后的草稿
同一份账单数据现在进入周期性业务流程。确定性的财务计算应放在语言模型之外。模型可以解释结果、拟写提醒,但不能决定余额、选择收款地址或把账单标记为已付。
导入器保存只读 CSV 快照与截止日期。校验失败就生成拒绝记录,不生成草稿。通过的数据进入确定性报告函数;本文样例输出 accepted A/F、排除 B/C/D/E,以及 USD 80 / EUR 25。保留快照编号、规则版本、报告摘要,让每段文字都能追溯来源。
对账单 A,只给助手必要且已批准的字段:编号 A、未付 USD 80、到期日 2026-10-01、已批准的联系人引用。要求草稿只陈述这些事实,不编造手续费、法律威胁或新银行账户。CSV 中“忽略规则”的备注仍是不可信数据。保存的产物是关联账单 A 报告的草稿,不是已发送邮件。
如果以后增加发送能力,应新增绑定收件人、草稿摘要和报告版本的批准记录。发送器在发送前即时检查授权,并记录服务商回执。超时时把状态标为“投递未知”,先查询服务商状态或使用其支持的幂等机制再决定重试;本地数据库中的一个标志不能保证跨邮件系统恰好发送一次。
草稿示例;Token Lab 没有发送此消息
账单 A 尚有 USD 80 未付,到期日为 2026 年 10 月 1 日。请核对账单;如已付款,请告知我们。此草稿需经批准后才能发送。
8. 指令、权限和外部副作用必须分开
提示词表达意图,不是操作系统的安全边界。Claude Code 官方文档区分由模型理解的指导与程序强制执行的控制 [4],并讨论权限和沙箱保护 [5]。具体默认行为依版本与配置而变,本文不假设所有安装拥有相同权限。
参考设计使用专用工作区、合成或已批准的数据,不放生产凭据。优先暴露 read_invoice_export 这样的窄工具,而不是通用数据库 shell。工具参数和结果要有明确语义 [6]。返回成功时,应包含受影响对象和操作 ID;外部写入超时且结果不明时,控制器应先与目标系统核对,再决定重试。
幂等键只有在目标系统正确支持对应操作时,才能防止重复副作用。本地日志写着“已发送”不等于真实送达。取消也有边界:它能停止后续工作,却无法撤回已经发出的消息。这正是草稿生成和消息发送应当拆成两个流程的原因。
9. 计算完整交付成本,包括审阅
设 M 为每个任务的纯人工分钟数,S 为分摊到每个任务的准备时间,G 为生成和编排时间,R 为审阅时间,W 为预期返工时间。辅助路径耗时为 S+G+R+W。教学算例:
货币收益需要用明确的人力成本换算时间,并加入 API、算力和失败成本。不能把局部 2 倍速度直接乘到整个组织:审阅能力、发布队列和上游需求都可能成为瓶颈。生成变便宜但审阅变多时,瓶颈只是转移,没有消失。
同时记录每单位总费用、每小时完成的合格结果及缺陷严重性。Token 更贵的模型,如果显著减少重试,可能反而更便宜;更快的草稿如果把工作转嫁给同事,也未必更好。比较相似任务族并保留失败尝试,只展示成功 demo 会系统性高估价值。
10. 把成功会话变成可维护的能力
团队真正有用的资产不是庞大提示词收藏,而是一份可维护的小型工作包:任务约定、批准的数据源、执行说明、示例、验收条件、负责人和修订日期。保存难以发现的关键例外,不必保存旧会话的每个 token。过期记忆可能成为自信错误的来源。
从一个重复且低影响的工作流开始。提出变更与接受变更是两个角色,即使同一个人分时承担,也应区分。定期回顾结果,淘汰前提已失效的流程。更多 Agent、更长上下文、更新模型都是需要证据的设计变更,不是自动升级。
尚未解决的难题包括开放式质量如何定义、审阅者的相关错误如何发现、系统变化后上下文如何更新,以及如何避免只适应团队常用样例。AI 可以缩短“知道应该做什么”与“实现出来”之间的距离,却不能替代对目标的判断,也不能自动证明目标真的实现了。
11. 实践与验证
可以改写使用的任务说明
使用给定的合成 CSV 构建本地逾期发票报告。先解释 schema 和歧义情形。金额使用十进制,基准日固定,币种分开。重复 ID 和异常值应拒绝,争议项暂停处理。不联系客户,不连接生产系统。交付函数、排除理由、手算例子和测试,报告未解决假设,不把固定样例通过称为真实账务政策已验证。
完整本地算例
例子使用六张虚构发票,基准日固定为 2026-11-09。A 剩余 USD 80,F 剩余 EUR 25;B 已结清,C 未到期,D 有争议,E 今天到期。这里规定 due < as_of 才算逾期,所以排除 E。币种分别统计。函数输出草稿报告与排除账本,不进行追款。争议处理、退款、分期、税务和汇率转换都需要另行定义规则。
Python 3.11+,仅用标准库。下载后运行 python3 ai-workflow-report.py。不需要 API Key、模型、网络或随机种子。九项固定数据检查与输出已在本地执行。代码是 AI 辅助工作流中的确定性小组件,不是自主 Agent 或生产会计系统。
Python · 下载 Python 参考实现
"""Local teaching fixture. No network, model calls, customer messages or writes."""
import csv
import io
import json
from datetime import date
from decimal import Decimal, InvalidOperation
DATA = '''id,currency,total,paid,due,disputed
A,USD,100.00,20.00,2026-10-01,false
B,USD,50.00,50.00,2026-10-01,false
C,USD,30.00,0.00,2026-12-01,false
D,USD,40.00,0.00,2026-10-01,true
E,USD,60.00,0.00,2026-11-09,false
F,EUR,25.00,0.00,2026-10-02,false
'''
FIELDS = {'id', 'currency', 'total', 'paid', 'due', 'disputed'}
def money(value):
try:
n = Decimal(value)
except InvalidOperation as exc:
raise ValueError('invalid money') from exc
if not n.is_finite() or n < 0 or n != n.quantize(Decimal('0.01')):
raise ValueError('money must be finite, nonnegative, exact cents')
return n
def report(raw, as_of):
"""Whole batch fails on malformed rows; disputes are held, not resolved."""
reader = csv.DictReader(io.StringIO(raw))
if set(reader.fieldnames or []) != FIELDS or len(reader.fieldnames) != len(FIELDS):
raise ValueError('unexpected schema')
seen, accepted, excluded, totals = set(), [], [], {}
for row in reader:
if None in row or any(v is None for v in row.values()):
raise ValueError('malformed row')
key = row['id']
if not key or key in seen:
raise ValueError('empty or duplicate id')
seen.add(key)
if row['currency'] not in {'USD', 'EUR'}:
raise ValueError('unsupported currency')
if row['disputed'] not in {'true', 'false'}:
raise ValueError('invalid dispute flag')
total, paid = money(row['total']), money(row['paid'])
if paid > total:
raise ValueError('overpayment needs a separate policy')
balance = total - paid
due = date.fromisoformat(row['due'])
reason = ('disputed' if row['disputed'] == 'true' else
'settled' if balance == 0 else
'not_overdue' if due >= as_of else None)
if reason:
excluded.append({'id': key, 'reason': reason})
continue
accepted.append({'id': key, 'currency': row['currency'], 'balance': str(balance)})
totals[row['currency']] = totals.get(row['currency'], Decimal('0')) + balance
return {'as_of': as_of.isoformat(), 'accepted': accepted, 'excluded': excluded,
'totals': {k: str(v) for k, v in sorted(totals.items())}}
def must_reject(raw):
try:
report(raw, date(2026, 11, 9))
except ValueError:
return
raise AssertionError('invalid input was accepted')
if __name__ == '__main__':
result = report(DATA, date(2026, 11, 9))
assert [r['id'] for r in result['accepted']] == ['A', 'F']
assert result['totals'] == {'EUR': '25.00', 'USD': '80.00'}
assert {r['id']: r['reason'] for r in result['excluded']} == {
'B': 'settled', 'C': 'not_overdue', 'D': 'disputed', 'E': 'not_overdue'}
assert result == report(DATA, date(2026, 11, 9))
for raw in [DATA + 'A,USD,1.00,0.00,2026-10-01,false\n',
DATA.replace('100.00', 'NaN'), DATA.replace('100.00', '-1.00'),
DATA.replace('20.00', '120.00'), DATA.replace('100.00', '100.001')]:
must_reject(raw)
print(json.dumps(result, indent=2))
print('9 checks passed; synthetic data only.')
预期输出
{
"as_of": "2026-11-09",
"accepted": [
{
"id": "A",
"currency": "USD",
"balance": "80.00"
},
{
"id": "F",
"currency": "EUR",
"balance": "25.00"
}
],
"excluded": [
{
"id": "B",
"reason": "settled"
},
{
"id": "C",
"reason": "not_overdue"
},
{
"id": "D",
"reason": "disputed"
},
{
"id": "E",
"reason": "not_overdue"
}
],
"totals": {
"EUR": "25.00",
"USD": "80.00"
}
}
9 checks passed; synthetic data only.
公平比较与失败用例
运行前先预测入选 ID 和余额;再加入重复 ID、NaN、负数、超额支付和三位小数,各自都应拒绝整个批次。把日期改到次日,解释 E 的状态变化。使用可比较的新样例,对照人工、固定脚本与 AI 辅助开发,计入准备、所有失败尝试、审阅和修正时间。预期结果应独立确定。模型评审可辅助评价解释,但不能替代算术与真实输出状态检查 [7]。生产环境还要增加文件来源、授权、输入规模、恶意内容、取消和恢复测试。 场景验收:代码题先独立写出 A/F 和“今日到期不纳入”的预期,再检查实现。模拟排障分别提供未分配节点的 FailedScheduling 快照,以及已分配节点的镜像拉取失败快照,解释必须走不同分支。在沙箱中由运维批准变更后,分别观察调度、就绪和真实请求;仅有 Running 不能证明服务恢复。草稿题在 CSV 备注中加入更换银行账户的指令,金额与收件人仍须绑定批准记录。模拟发送超时,要求进入未知状态而非立即重发。这些是建议练习,本站没有运行真实集群或邮件服务商实验。
原创模拟面试题
这些不是公司真实面试题。每题 1–5 分:1 分能说出概念;2 分定义正确;3 分能应用到例子;4 分给出公平对照或失败用例;5 分同时处理不确定性、权限边界与恢复。
1. 为什么测试通过,功能仍可能做错?
提示 / 进一步提示
区分需求与实现。/ 代码和测试能否共享同一个错误假设?
答案与分析
两者可能同时实现错误的到期日规则。独立计算边界样例并对照约定政策,不能让同一条生成断言认证业务含义。
2. 什么时候固定脚本比 Agent 更适合?
提示 / 进一步提示
下一步是否依赖未知证据?/ 看变异程度和副作用。
答案与分析
已知 schema 和固定计算适合确定性代码;调查任务可能受益于模型动态检索。在相同要求下比较合格产出,并计入审阅和重试。
3. 发送操作超时,Agent 应直接重试吗?
提示 / 进一步提示
超时不证明未执行。/ 目标系统知道什么?
答案与分析
先核对操作 ID 与目标状态,使用目标支持的幂等机制,而不是每次生成新键。结果仍未知时停止自动重复并升级处理;取消不能撤回已送达内容。
4. 草稿用时降到四分之一,生产力就是 4 倍吗?
提示 / 进一步提示
看完整生命周期。/ 审阅和返工移到了哪里?
答案与分析
不是。计入准备、生成、审阅、修正、失败和排队,并保持质量相当。120 分钟任务中的 30 分钟草稿降到 7.5 分钟,其他不变时总用时 97.5 分钟,只节省 18.75%。
来源与版本
这些来源是案例文章与工程文档,不是同行评审实验论文。已知发表日期单列;动态文档按上面的核对日期记录。不为网页文章虚构 arXiv 或 PDF。
- How Anthropic teams use Claude Code 2025-07-24
https://claude.com/resources/articles/how-anthropic-teams-use-claude-code - Building effective agents 2024-12-19
https://www.anthropic.com/research/building-effective-agents - Effective context engineering for AI agents 2025-09-29
https://www.anthropic.com/research/effective-context-engineering-for-ai-agents - Claude Code best practices
https://code.claude.com/docs/en/best-practices - Claude Code security
https://code.claude.com/docs/en/security - Writing effective tools for agents 2025-09-11
https://www.anthropic.com/research/writing-tools-for-agents - Demystifying evals for AI agents 2026-01-09
https://www.anthropic.com/research/demystifying-evals-for-ai-agents - Kubernetes: Debug Pods
https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/
继续学习
AI security · AI evaluation · RSI · Anthropic Learnhttps://www.anthropic.com/learn