30 篇文章带有标签 “claude-code”

这是一份可以照着做的 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" —— 《程序员修炼之道》

实践记录：在上一篇里，我用 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 → 刷新）

为什么流向变了？两个现实约束：

1. Figma 对 AI 只读。免费（Starter）账号下 REST API 只读且限流严格，官方 Dev Mode MCP 的完整能力需要付费席位。AI 没有"在 Figma 里创作"的手。
2. HTML 是 AI 的天然设计稿。真实排版引擎渲染、可交互、秒级迭代，保真度甚至高于画板。

实践记录：我用 Claude Code 加 mattpocock/skills 技能集，从零开发了一款 macOS 原生应用「长辈计算器」。本文以这次真实开发为主线，拆解这套"AI 原生"软件工程流水线的每个环节、它背后的设计哲学，以及实战中暴露的问题。原始对话实录见前一篇。

一、为什么是"AI 原生"而不是"AI 辅助"

大多数人的 AI 编码方式是：打开编辑器，描述一个需求，AI 吐出代码，人肉检查。这是 AI 辅助——AI 是打字快的初级程序员，工程过程还是人的那套。

AI 原生的含义不同：整个软件工程过程——需求澄清、规格化、任务拆解、实现、测试、评审——都围绕 AI 的特性重新设计。AI 的特性是什么？

AI 的特性	对工程过程的要求
上下文窗口有限，塞满后质量衰减	任务必须切成"单个上下文能装下"的批次
每次会话开始时最"清醒"	频繁开新会话，而不是一条会话干到底
不会主动追问，猜错了就错到底	需求阶段强制访谈，分歧在写代码前解决
产出无限、判断有限	人只做检查点决策，不做中间执行
记不住上一次的对话	共识必须落盘为文件，而不是留在脑子里

mattpocock/skills 就是围绕这张表设计的。

原文：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. 简单至上

用最少的代码解决问题。不添加任何推测性内容。

• 不添加需求以外的功能。
• 不为一次性代码创建抽象。
• 不提供未要求的“灵活性”或“可配置性”。
• 不对不可能发生的场景进行错误处理。
• 如果你写了 200 行，而本可以 50 行完成，那就重写。

问问自己：“一位资深工程师会认为这过于复杂吗？” 如果会，就简化它。

3. 外科手术式的修改

只碰你必须改的。只清理你自己弄乱的。

编辑现有代码时：

• 不要“改进”相邻的代码、注释或格式。
• 不要重构没有坏的东西。
• 即使你有不同做法，也要遵循现有风格。
• 若注意到无关的无效代码，提出来——但不要删除。

当你的修改造成孤立代码时： 删除由你的修改导致的未使用的导入/变量/函数。

罗福莉 2026年4月6日

两天前，Anthropic 切断了第三方客户端（Harnesses）使用 Claude 订阅的通道——这并不令人意外。三天前，MiMo 推出了其 Token 计划（Token Plan）——这是一个我投入了大量精力去设计的方案，也是我认为在实现合理的算力分配和智能体客户端开发方面一次严肃的尝试。将这两件事结合起来，我有以下几点思考：

1. Claude Code 的订阅制是一个专为平衡算力分配而设计的精美系统。 我的猜测是——它并不赚钱，甚至可能在亏本，除非他们的 API 利润率高达 10-20 倍，但我对此深表怀疑。虽然我无法严密地计算出第三方客户端接入所带来的损失，但我近距离观察过 OpenClaw 的上下文管理——它真的很糟糕。在单个用户查询中，它会把一轮轮低价值的工具调用作为独立的 API 请求发送出去，每个请求都携带长达 100K 以上 Token 的长上下文窗口——即便有缓存命中，这也是极大的浪费，在极端情况下还会推高其他查询的缓存未命中率。其单次查询的实际请求次数最终比 Claude Code 自身框架高出数倍。折算成 API 定价的话，真实成本恐怕是订阅价格的几十倍。这不仅是一个差距，而是一个巨大的黑洞。
2. 像 OpenClaw/OpenCode 这样的第三方客户端依然可以通过 API 调用 Claude——它们只是不能再薅订阅制的羊毛了。 短期内，这些智能体用户会感到阵痛，成本极有可能飙升几十倍。但这种压力恰恰会倒逼这些客户端去优化上下文管理、最大化提升提示词缓存（Prompt Cache）的命中率以复用已处理的上下文，并减少无谓的 Token 消耗。痛苦最终会转化为工程上的严谨与克制。
3. 我强烈呼吁大模型公司不要在搞清楚如何为编程套餐定价且不亏本之前，就盲目地进行价格战、卷到行业底层。 廉价销售 Token 却对第三方客户端敞开大门，看似对用户友好，实则是一个陷阱——正是 Anthropic 刚刚踩进去又退出来的那个陷阱。更深层次的问题在于：如果用户把精力浪费在低质的智能体客户端、极度不稳定且缓慢的推理服务，以及为了削减成本而降级的大模型上，结果却发现依然什么事也做不成——这对于用户体验或留存率来说，绝不是一个健康的循环。
4. 关于 MiMo Token 计划——它支持第三方客户端，按 Token 配额计费，这与 Claude 最新推出的额外用量包逻辑一致。 因为我们追求的是长期、稳定地交付高质量的模型与服务——而不是吸引你冲动消费后便任由你弃船而去。

什么是 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 倍，零配置开箱即用。

安装 code-review-graph

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

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/

• Configuration Scopes

插件市场

注册插件市场

命令行运行：

claude plugin marketplace add obra/superpowers-marketplace

Claude Code 中运行：

论文基础信息

• 论文：Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering
• 论文ID：arXiv:2604.08224
• 发布时间：2026-04-09
• 核心定位：首篇系统梳理LLM智能体Harness工程的综述论文，提出了基于认知外化理论的智能体设计统一框架

核心观点

可靠的智能体能力不只是来自更强的模型本身，而是来自将认知负担系统性地转移到外部组件：

• 记忆外化：解决跨会话状态延续问题
• 技能外化：复用成熟的流程经验，避免每次都重新推理
• 协议外化：标准化交互规则，让工具调用、多智能体协作更稳定
• Harness（智能体引擎/管控框架） 是协调以上所有组件的统一运行层，是智能体系统的"认知环境"

什么是Harness？

Harness不是普通的工具链或者SDK，而是模型运行的完整认知环境：

• 模型本身只有通用推理能力，Harness决定了它能访问什么数据、能执行什么操作、怎么受到约束、怎么从错误中学习
• 智能体的能力不是模型单独具备的，而是模型和Harness环境耦合之后共同产生的
• Harness的核心作用是把零散的外部组件（内存、技能、协议）组合成连贯的智能行为，把无边界的推理任务转化为结构化的可控执行流程

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 的工作流包括：

1. 数据摄入：源文档（文章、论文、代码库、数据集、图像）被索引到 raw/ 目录
2. Wiki 编译：LLM 增量地"编译"原始数据成 markdown 文件的 wiki，包含摘要、反向链接、分类概念和相互链接的文章
3. IDE：Obsidian 用作前端查看原始数据、编译后的 wiki 和可视化
4. 问答：LLM 可以通过研究相关数据来回答针对 wiki 的复杂问题
5. 输出：结果渲染为 markdown 文件、Marp 幻灯片或 matplotlib 图像，可在 Obsidian 中查看
6. Linting：LLM"健康检查"发现不一致、填补缺失数据、建议新文章候选
7. 额外工具：诸如 wiki 上的朴素搜索引擎等额外工具

核心原则

• LLM 编写和维护所有 wiki 数据；手动编辑很少见
• 用户探索和查询被归档回 wiki 以增强它
• 系统专注于 markdown 文件和 Obsidian 兼容格式
• 图像被下载到本地 以便 LLM 轻松引用

目录结构

创建 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 工作流管理等工作。

核心特性

• 基于 Anthropic Claude 大语言模型
• 高度可扩展的插件架构
• 安全的工具调用和权限管理
• 支持多种工作流和集成

二、项目目录结构

Claude 代码安全审查 (Claude Code Security Review) 是一个基于 AI 的 GitHub Action 安全审查工具，利用 Claude 分析代码变更中的安全漏洞。包含了我个人的二次开发成果（Web 界面、全库扫描、可视化报告）。

Claude 代码安全审查器 (Claude Code Security Reviewer)

这是一个基于 AI 驱动的 GitHub Action 安全审查工具，利用 Claude 分析代码变更中的安全漏洞。该 Action 使用 Anthropic 的 Claude Code 工具进行深度语义安全分析，为 Pull Request (PR) 提供智能且具备上下文感知能力的安全评估。

功能特性

• AI 驱动分析：利用 Claude 先进的推理能力，通过深度语义理解来检测安全漏洞。
• 差异感知扫描：针对 PR，仅分析发生变更的文件。
• PR 自动评论：自动在 PR 中针对发现的安全问题发布评论。
• 上下文理解：超越简单的模式匹配，深入理解代码的语义逻辑。
• 语言无关性：支持任何编程语言。
• 误报过滤：通过高级过滤功能减少干扰，专注于真正的安全漏洞。

快速入门

将以下内容添加到您仓库的 .github/workflows/security.yml 文件中：