Claude Code 最佳实践 · 网格版文档HTML
「Claude Code 官方最佳实践中文整理:先分清确定性指令与非确定性指令,再补上它看不到的信息、给一个能跑的检查、用 hook 与权限规则兜住例外,并调整 effort、成本与无人值守运行的默认设置,末尾列出已可放弃的旧建议。」
「Claude Code 官方最佳实践中文整理:先分清确定性指令与非确定性指令,再补上它看不到的信息、给一个能跑的检查、用 hook 与权限规则兜住例外,并调整 effort、成本与无人值守运行的默认设置,末尾列出已可放弃的旧建议。」
这是一份可以照着做的 AI 原生软件开发工作流指南。我用 Claude Code 加 mattpocock/skills 技能集,从零开发了一款 macOS 原生应用「长辈计算器」,并在交付后走完了完整的架构演进循环。本文拆解这条工作流的每一个环节——为什么这样设计(所以然)、具体怎么做(操作步骤)、实战中长什么样(真实证据)——让没有经验的开发者也能照着走完全程。完整对话实录见实践实录,速读版见上一篇实践总结。
一、为什么需要「AI 原生」工作流
大多数人的 AI 编码方式是:打开编辑器,描述一个需求,AI 吐出代码,人肉检查。这是 AI 辅助——AI 是打字快的初级程序员,工程过程还是人的那套。
AI 原生的含义不同:整个软件工程过程——需求澄清、规格化、任务拆解、实现、测试、评审、演进——都围绕 AI 的特性重新设计。
1.1 四个经典失败模式
mattpocock/skills 的作者 Matt Pocock 在仓库 README 里总结了他观察到的四个 AI 编码失败模式,这套技能集就是对着这四个失败模式设计的。理解它们,就理解了整条工作流的"所以然":
失败模式 #1:智能体做的不是我要的(misalignment)
"No-one knows exactly what they want" —— 《程序员修炼之道》
以 mattpocock/skills 的 37 个技能为蓝本,完整拆解从模糊想法到可合并代码的 AI 原生开发全流程:每个环节做什么、该用哪个技能、为什么这样设计,并附可照抄的落地检查清单与技能逐条详解。
实践记录:在上一篇里,我用 Claude Code + mattpocock-skills 走通了 AI 原生的开发流水线。这一次,我把目光投向开发之前被忽略的环节——设计。我基于 Google 的 DESIGN.md 规范,为「长辈计算器」建立了完整的设计流水线:从现有网站提炼设计规范 → 生成高保真 HTML 原型 → 导入 Figma → 与代码对齐。本文拆解每个阶段的做法、工具的能力边界,以及实战中踩过的六个坑。
一、范式转变:设计的事实源搬家了
传统 SDLC 中,设计的事实源(single source of truth)是 Figma:设计师在画板上创作,开发通过"交付"把设计变成代码。AI 原生 SDLC 中,事实源上移到仓库里的文本规范——因为文本是 AI 的原生格式:可读、可 diff、可 lint、可版本化。
| 传统流向(人主导) | AI 原生流向(AI 主导) | |
|---|---|---|
| 事实源 | Figma 画板 | 仓库里的 DESIGN.md |
| 设计稿形态 | Figma 帧 | HTML 高保真原型 |
| Figma 的角色 | 创作层 | 协作与存档层 |
| 迭代成本 | 分钟级(人工拖图层) | 秒级(改 prompt → 刷新) |
为什么流向变了?两个现实约束:
实践记录:我用 Claude Code 加 mattpocock/skills 技能集,从零开发了一款 macOS 原生应用「长辈计算器」。本文以这次真实开发为主线,拆解这套"AI 原生"软件工程流水线的每个环节、它背后的设计哲学,以及实战中暴露的问题。原始对话实录见前一篇。
一、为什么是"AI 原生"而不是"AI 辅助"
大多数人的 AI 编码方式是:打开编辑器,描述一个需求,AI 吐出代码,人肉检查。这是 AI 辅助——AI 是打字快的初级程序员,工程过程还是人的那套。
AI 原生的含义不同:整个软件工程过程——需求澄清、规格化、任务拆解、实现、测试、评审——都围绕 AI 的特性重新设计。AI 的特性是什么?
| AI 的特性 | 对工程过程的要求 |
|---|---|
| 上下文窗口有限,塞满后质量衰减 | 任务必须切成"单个上下文能装下"的批次 |
| 每次会话开始时最"清醒" | 频繁开新会话,而不是一条会话干到底 |
| 不会主动追问,猜错了就错到底 | 需求阶段强制访谈,分歧在写代码前解决 |
| 产出无限、判断有限 | 人只做检查点决策,不做中间执行 |
| 记不住上一次的对话 | 共识必须落盘为文件,而不是留在脑子里 |
mattpocock/skills 就是围绕这张表设计的。
逐节点拆解 Anthropic《The AI-Native SDLC Playbook》:六阶段闭环、工件驱动的自动交接、skill 与 hook 双层控制、成对度量,附 11 张手绘 SVG 结构图与反模式清单。
原文:The AI-Native SDLC playbook(Anthropic Applied AI 团队) 译者注:本文为完整中文翻译,英文术语首次出现时保留原文。
代码不再是瓶颈
组织已经开始以一年前难以想象的速度用 AI 编写代码,但围绕代码的流程并没有以同样的速度改变。
许多工程团队仍然沿用同样的审批关卡、评审、交接和策略,这使得使用 Claude Code 等智能体编程解决方案带来的生产力提升被拖延抵消。
软件开发生命周期(SDLC)是将软件从想法带到生产环境的过程。大多数组织运行的都是同样六个阶段的某种版本,涵盖规划、设计、构建、测试、部署和维护软件。传统上,每个阶段都是一个由不同角色负责的独立阶段:产品经理写需求,技术架构师把需求变成设计,工程师按设计实现,受监管企业的 QA 团队进行验证,发布团队负责上线,运维团队监控运行状况。工作在阶段之间通过文档、工单和签字确认来流转。
传统的软件开发生命周期(SDLC)流程繁重,是为了确保每一步的责任与控制。然而,传统 SDLC 的设计初衷是在「编写和实现代码」这一最耗时、最昂贵阶段的年代最大化效率——而这个前提已经不复存在。PRD、估点仪式和产品安全评审,本质上都是为了在长达数周、数月甚至数个季度的开发过程中强制对齐。
传统 SDLC 的另一点是:它的各种控制措施假设每一步都由人来执行。
下面是 CLAUDE.md 文件的内容,用于改善 Claude Code 的行为,源自 Andrej Karpathy 的观察 关于 LLM 编码陷阱的总结。
CLAUDE.md
旨在减少大语言模型常见编码错误的行为准则。可根据项目特定说明按需合并。
权衡: 本准则偏向谨慎而非速度。对于琐碎任务,请自行判断。
1. 编码前先思考
不要假设。不要掩饰困惑。要呈现权衡。
实施之前:
2. 简单至上
用最少的代码解决问题。不添加任何推测性内容。
问问自己:“一位资深工程师会认为这过于复杂吗?” 如果会,就简化它。
3. 外科手术式的修改
只碰你必须改的。只清理你自己弄乱的。
编辑现有代码时:
当你的修改造成孤立代码时: 删除由你的修改导致的未使用的导入/变量/函数。
罗福莉 2026年4月6日
两天前,Anthropic 切断了第三方客户端(Harnesses)使用 Claude 订阅的通道——这并不令人意外。三天前,MiMo 推出了其 Token 计划(Token Plan)——这是一个我投入了大量精力去设计的方案,也是我认为在实现合理的算力分配和智能体客户端开发方面一次严肃的尝试。将这两件事结合起来,我有以下几点思考:
什么是 Claude Code

应用于软件开发的各个阶段
| 1. 探索 (Discover) |
2. 设计 (Design) |
3. 构建 (Build) |
4. 部署 (Deploy) |
5. 维护与扩展 (Support & Scale) |
|---|---|---|---|---|
| 探索代码库与历史 (Explore codebase and history) |
规划项目 (Plan project) |
实现代码 (Implement code) |
自动化 CI/CD (Automate CI/CD) |
调试错误 (Debug errors) |
| 搜索文档 (Search documentation) |
制定技术规范 (Develop tech specs) |
编写并执行测试 (Write and execute tests) |
配置环境 (Configure environments) |
大规模重构 (Large-scale refactor) |
| 入职与环境配置 (Onboard & Setup) |
定义架构 (Define architecture) |
创建提交与 PR (Create commits and PRs) |
管理部署 (Manage deployments) |
监控使用情况与性能 (Monitor usage & performance) |
工具使用


内置工具列表
安装 Claude Code
1. Native 安装(推荐)
⚠️ 国内用户会出现不能访问或卡住的问题。
curl -fsSL https://claude.ai/install.sh | bash
安装后的可执行文件路径:/Users/junjian/.local/bin/claude
下面是安装卡住,但是程序已经下载成功,我手动安装完成的过程:
下载的二进制文件会被保存在 ~/.claude/downloads 目录下:
ll ~/.claude/downloads
-rwxr-xr-x 1 junjian staff 205M 5月 29 22:56 claude-2.1.156-darwin-arm64
我们需要把它移动到 ~/.local/share/claude/versions 目录下,并创建一个软链接到 ~/.local/bin:
Thariq: Using Claude Code: The Unreasonable Effectiveness of HTML
Markdown 已成为智能体(agent)与我们沟通时占主导地位的文件格式。它简单、可移植,具备一定的富文本能力,且易于编辑。Claude 甚至已经相当擅长在 Markdown 文件中使用 ASCII 绘制图表。
但随着智能体变得越来越强大,我感到 Markdown 已成为一种受限的格式。我发现自己很难阅读超过一百行的 Markdown 文件。我想要更丰富的可视化效果、色彩和图表,并且希望能轻松分享它们。
我也越来越不亲自编辑这些文件,而是将它们用作规格说明、参考文件、头脑风暴输出等。当我确实需要编辑时,我通常会让 Claude 来编辑,这就削弱了 Markdown 最大的一个优势。
我开始更偏爱 HTML 作为输出格式,而不是 Markdown,并且越来越多地看到 Claude Code 团队中的其他人也在使用它。以下就是原因。
(如果你想先看一些示例,可以在这里看到一大堆:https://thariqs.github.io/html-effectiveness ,不过记得回来看更多关于"为什么"的内容。)
为什么选择 HTML?
信息密度

与 Markdown 相比,HTML 能够传达更丰富得多的信息。
code‑review‑graph 是一款为 AI 编程助手打造的本地代码知识图谱工具,核心是用增量图谱替代全量读码,大幅降低 AI 上下文 Token 消耗、提升代码审查与理解效率。
基于 Tree‑sitter 解析代码结构,构建持久化增量知识图谱,通过 MCP 协议给 AI 提供精准最小上下文,Token 用量可降 5–10 倍,零配置开箱即用。
pip install code-review-graph
将 MCP Server 注册到 AI 编程平台
# cd <project-root>
code-review-graph install --platform claude-code
这是一个通过多智能体(multi-agent)流水线将代码库或知识库转化为交互式知识图谱,并提供可视化看板和 AI 问答功能的 Claude Code 插件。
Understand Anything 将任意代码库、知识库或文档转化为可探索、可搜索、可对话的交互式知识图谱,支持 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等多平台。
多智能体架构
/understand 命令调用 5 个 agent,/understand-domain 额外增加第 6 个:
| Agent | 职责 |
|---|---|
project-scanner |
扫描项目文件,检测语言和框架 |
file-analyzer |
提取代码结构(函数、类和导入),生成图节点和边 |
architecture-analyzer |
识别架构层 |
tour-builder |
生成引导式学习路径 |
graph-reviewer |
验证图的完整性和引用完整性 |
domain-analyzer |
提取业务领域、流程和处理步骤(由 /understand-domain 使用) |
article-analyzer |
从 wiki 文章中提取实体、论断和隐式关系(由 /understand-knowledge 使用) |
文件分析器并行运行(最多 3 个并发)。支持增量更新 — 仅重新分析自上次运行以来发生更改的文件。
Claude Code
| User(用户范围) | Project(项目范围) | Local(本地范围) | |
|---|---|---|---|
| 生效范围 | 当前用户(跨所有项目) | 该仓库的所有协作人员 | 仅限当前项目的当前用户 |
| Settings 配置文件路径 |
~/.claude/settings.json |
.claude/settings.json |
.claude/settings.local.json |
| CLAUDE.md 指令文档 |
~/.claude/CLAUDE.md |
CLAUDE.md or .claude/CLAUDE.md |
CLAUDE.local.md |
| Skills 技能安装路径 |
~/.claude/skills/ |
.claude/skills/ |
|
| Plugins 插件安装路径 |
~/.claude/plugins/ |
.claude/plugins/ |
|
| MCP Server MCP 服务器配置 |
~/.claude.json |
.mcp.json |
|
| Subagents 子智能体配置 |
~/.claude/agents/ |
.claude/agents/ |
插件市场
注册插件市场
命令行运行:
claude plugin marketplace add obra/superpowers-marketplace
Claude Code 中运行:
论文基础信息
核心观点
可靠的智能体能力不只是来自更强的模型本身,而是来自将认知负担系统性地转移到外部组件:
什么是Harness?
Harness不是普通的工具链或者SDK,而是模型运行的完整认知环境:
gstack 是由 YC 首席执行官 Garry Tan 发起的开源智能体技能集(Skills),旨在将 Claude Code 等 AI 编程助手重塑为一支全栈虚拟开发团队。它通过一套高度专业化的指令流,实现了从产品构思、架构设计、自动化编码到代码评审、质量保障及发布部署的软件全生命周期闭环开发。

你: 我想为我的日历做一个每日简报应用。
你: /office-hours(发起咨询)
Claude: [询问痛点 —— 要求提供具体的例子,而不是假设]
你: 多个 Google 日历,活动信息已过时,地点也是错的。
准备工作耗时太长,而且效果不够好……
Claude: 我想挑战一下你的设定。你说的是“每日简报应用”,但你实际描述的是一个“AI 私人幕僚长”。
[提取了 5 项你甚至没意识到自己已经描述出的功能]
[挑战了 4 个前提 —— 你对此表示同意、反对或进行调整]
[生成了 3 种实施方案及工作量预估]
建议: 明天先上线最核心的切入点,从实际使用中学习。完整愿景是一个为期 3 个月的项目 ——
先从一个真正好用的每日简报开始。
[编写设计文档 → 自动同步至下游技能]
// ...
英文版本:
WikiLLM
利用 LLM 构建个人知识库的系统。WikiLLM 将原始素材"编译"成结构化、交叉链接的高质量中文 Wiki,可在 Obsidian 中查看。
本项目基于 Andrej Karpathy 提出的理念构建。详见:LLM Knowledge Bases

项目概述
WikiLLM 的工作流包括:
raw/ 目录核心原则
目录结构
创建 CLAUDE.md
这样它会将项目的规范、构建命令和架构要点记录下来,后续对话中它会自动参考这个文件,不再需要你重复解释背景。有利于后续的代码分析、调试和功能开发。
运行 /init 命令
/init - 自动分析该项目并生成 CLAUDE.md
我已为该仓库成功创建了CLAUDE.md文件。以下是文件包含的内容:
### CLAUDE.md 内容概要
1. **概述** - 包含项目统计信息(约1884个文件、51.2万行代码、40+工具、80+命令)的项目说明,以及法律免责声明。
2. **命令** - 构建与开发相关命令:
- `npm run prepare-src` - 准备源码
- `npm run build` - 使用esbuild构建
- `npm run check` - 执行类型检查
- `npm start` - 运行编译后的命令行工具
3. **高层架构**:
- src/query.ts中的核心智能体循环模式
- 核心目录(入口点、命令行、命令、工具、组件、服务、状态、工具函数)
- 关键文件及其用途
// ...
CLAUDE.md
本文件用于指导 Claude Code(claude.ai/code)处理此代码仓库中的代码。
概述
本仓库包含 Claude Code v2.1.
一、项目概述
Claude Code 是 Anthropic 开发的一款终端智能体编码工具,通过自然语言与开发者交互,理解代码库上下文,自动化完成日常编码任务、代码审查、Git 工作流管理等工作。
核心特性
二、项目目录结构
没有找到匹配的文章