16 篇文章带有标签 “ai-coding”

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

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

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

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

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

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

摘要：在 LLM 标称上下文窗口动辄 1M、2M 的今天，工程落地的残酷真相却是：上下文用得越多，模型表现往往越差。本文基于 Smart Zone（黄金上下文区间） 概念，深度拆解上下文用量超越 40% 后的能力崩塌逻辑，剖析能力、行为、经济三大隐形边界，并结合“大文本处理”、“KV-Cache”等场景给出 Agent 上下文管理的最佳工程实践。

一、 引言：为什么上下文窗口越大，AI 反而越“傻”？

随着长上下文（Long-Context）技术的普及，许多开发者形成了一种思维惯性：把整个项目代码库、长篇文档、全量日志和全部历史对话一股脑塞给 AI Agent。

然而，HumanLayer 创始人 Dex Horthy 提炼出的工程实践法则表明：当上下文占用突破标称窗口的 40% 后，AI 的输出质量、推理准确率和任务完成度会面临急剧下滑。

为了直观展现这一现象，我们可以总结出Smart Zone（黄金上下文区间） 核心图景：

gantt
    title AI 编程助手上下文区间与边界示意图 (Smart Zone vs Danger Zone)
    dateFormat X
    axisFormat %s%%

    section 区间划定
    Smart Zone (黄金上下文区间)  :active, zone1, 0, 40
    Danger Zone (危险/衰减区间)  :crit, zone2, 40, 100

    section 核心边界拐点
    能力边界 (Accuracy Degrades, 16-24%)  :milestone, m1, 20, 20
    经济边界 (Cost Escalation, ~20%)      :milestone, m2, 20, 20
    行为边界 (Context Anxiety, ~30%)      :milestone, m3, 30, 30
    Safeguard Line (/clear 截断告警线, 40%) :milestone, m4, 40, 40

二、 核心公式：决定模型输出质量的两大隐形杠杆

在长上下文互动中，控制模型输出质量的本质是控制以下两个指标：

1. 信号密度（Signal Density）

$$\text{信号密度} = \frac{\text{任务相关 Token}}{\text{窗口内总 Token}}$$

• mattpocock-skills

安装

npx skills add mattpocock/skills

初始化（/setup-matt-pocock-skills）

/setup-matt-pocock-skills

在你的 agent 中，每个仓库运行一次。它会：

• 问你想使用哪个 issue tracker（GitHub、Linear 或本地文件）
• 问你在 triage ticket 时会给它们打什么标签（/triage 会用到标签）
• 问你想把我们创建的文档保存在哪里

目录结构

.
├── CLAUDE.md
└── docs
    └── agents
        ├── domain.md
        ├── issue-tracker.md
        └── triage-labels.md

软件开发工作流程

grill-with-docs → to-spec → to-tickets → implement (tdd → code-review) → code-review

/grill-with-docs

description

一场为锐化计划或设计而不留情面的访谈，过程中还会同步创建文档（ADR 与术语表）。调用 Skill 工具两次，分别传入 "grilling" 和 "domain-modeling"。

详细介绍

grill-with-docs 就一个方案或设计对你进行访谈，直到你和 ag

Simon Willison 的 《Agentic Engineering Patterns》（智能体工程模式） 是一份面向软件工程师的实践指南，重点探讨在 Coding Agents（如 Claude Code、OpenAI Codex、Cursor 等能自主生成并执行代码、运行测试的智能体）普及的新时代，如何高效、高质量地进行软件开发。

一、 核心理念：什么是智能体工程？

Agentic Engineering（智能体工程） 明确区别于 Vibe Coding（氛围编程）：

• Vibe Coding：通常指非程序员完全依赖 LLM 编写代码，自己不看也不理解代码细节。
• Agentic Engineering：专业软件工程师通过 Coding Agent 来放大（Amplify）自身的专业技能。工程师依然担任架构师与质量把关人的角色，而将重复性、确定性的机械操作交给 Agent。

1. 观念重塑：“代码变得极其廉价”

传统软件工程的核心约束是代码编写成本昂贵（写几百行优质代码需要数小时或数天），因此衍生出了大量的预先设计、工时评估与严格的 YAGNI（You Aren't Gonna Need It）原则。 在 Agent 时代：

• 初始代码的生成成本趋近于 0。
• 优质代码的维护与理解成本依然存在。
• 如果不对 Agent 生成的代码进行严格审查和测试，廉价的代码会迅速演变成庞大的技术债务（Technical Debt）。

在 AI 辅助编程风靡的今天，许多开发者沉浸于 Vibe Coding（氛围感编码）——直接抛出几句自然语言需求，交由 AI 自动生成代码。然而，这种“野蛮生长”的方式往往会导致需求理解偏差、架构快速腐化（Ball of Mud）、上下文遗忘以及越改 Bug 越多的困境。

Matt Pocock 的开源项目 mattpocock/skills 正是为了解决这一痛点而生。它不是一堆零散的 Prompt 集合，而是一套为 Claude Code、Codex 等 AI 编程智能体设计的系统化软件工程最佳实践。

官方体系将技能划分为两大类：

1. User-Invoked（用户触发）：由开发者在终端中通过命令显式调用（如 /grill-with-docs、/to-spec），用于任务编排与流程推进。
2. Model-Invoked（模型自主调用）：由 AI 在执行具体任务时自行判断并调用的工程纪律规范（如 /tdd、/codebase-design）。

工作流全景链路 (The Engineering Harness)

核心开发主流程遵循着从“模糊想法”到“高质量交付”的递进逻辑：

原文：The AI-Native SDLC playbook（Anthropic Applied AI 团队） 译者注：本文为完整中文翻译，英文术语首次出现时保留原文。

代码不再是瓶颈

组织已经开始以一年前难以想象的速度用 AI 编写代码，但围绕代码的流程并没有以同样的速度改变。

许多工程团队仍然沿用同样的审批关卡、评审、交接和策略，这使得使用 Claude Code 等智能体编程解决方案带来的生产力提升被拖延抵消。

软件开发生命周期（SDLC）是将软件从想法带到生产环境的过程。大多数组织运行的都是同样六个阶段的某种版本，涵盖规划、设计、构建、测试、部署和维护软件。传统上，每个阶段都是一个由不同角色负责的独立阶段：产品经理写需求，技术架构师把需求变成设计，工程师按设计实现，受监管企业的 QA 团队进行验证，发布团队负责上线，运维团队监控运行状况。工作在阶段之间通过文档、工单和签字确认来流转。

传统的软件开发生命周期（SDLC）流程繁重，是为了确保每一步的责任与控制。然而，传统 SDLC 的设计初衷是在「编写和实现代码」这一最耗时、最昂贵阶段的年代最大化效率——而这个前提已经不复存在。PRD、估点仪式和产品安全评审，本质上都是为了在长达数周、数月甚至数个季度的开发过程中强制对齐。

传统 SDLC 的另一点是：它的各种控制措施假设每一步都由人来执行。

原文：Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl 作者：Birgitta Böckeler（Thoughtworks 杰出工程师、AI 辅助交付专家，拥有 20 多年软件开发、架构与技术领导经验） 本文是"Exploring Gen AI"系列的一部分。该系列记录了 Thoughtworks 技术专家对使用生成式 AI 技术进行软件开发的探索。

我一直在尝试理解 AI 编程领域最新的流行语之一：规约驱动开发（Spec-driven development，SDD）。我研究了三个自称 SDD 工具的产品，并试图厘清截至目前它到底意味着什么。

定义

与这个快节奏领域中许多新兴术语一样，"规约驱动开发"（SDD）的定义仍在变化之中。以下是我从目前见到的用法中归纳出的理解：规约驱动开发意味着在用 AI 编写代码之前先编写一份"规约"（"文档先行"）。这份规约成为人与 AI 共同的真理来源（source of truth）。

GitHub："在这个新世界中，维护软件意味着演进规约。［……］开发的通用语言上移到了更高层次，而代码只是最后一公里的实现手段。"

Tessl："一种开发方法，其中规约——而非代码——是

00 摘要：10 条核心论断

这份报告不是工具评测，也不是范式百科。它的目标是回答一个工程决策问题：如果你要在 2026 年把 AI 编程从「个人提效」推到「团队与生产系统」，你该采用哪套范式、按什么顺序、用什么门禁？ 下面 10 条论断是全篇骨架，只读这一页也能拿走结论。

1. 位移点不在「写代码」，而在「定义意图 + 验证结果」。 代码正在从「资产」降格为「构建产物」。当重写一段代码的成本趋近于零，真正稀缺的是「为什么这么做」的可追溯记录与「这样做对不对」的判定能力。
2. 瓶颈已从生成迁移到验证。 生成的边际成本在两年内下降了一个数量级，验证的边际成本几乎没动。所有有效范式（SDD 的可执行验收标准、multi-agent 的 verifier 角色、TDD-as-gate）本质上都在做同一件事：压缩单位验证成本，而不是让评审更严格。
3. 规范的复兴不是复古，而是因为规范第一次变得可执行。 1980 年代的需求文档会腐烂，因为它不驱动任何东西。2026 年的 spec.md 直接驱动生成器、被 Git 版本化、被 CI 校验——可执行，才第一次值得写。
4. AI 是放大器，不是均衡器。 DORA 2025（n≈5,000）的核心结论：AI 放大高绩效组织的优势，也放大挣扎组织的失能。平台质量、数据生态、价值流管理决定收益的正负号，工具选择只决定幅度。
5. 个体提速的证据显著弱于感知，且高度依赖任务与代码库。 METR 的 RCT（16 名资深开发者 / 246 个真实任务）显示用时增加 19%，而参与者事后仍自认为快了 20%。用「感觉更快」做投资决策是危险的。
6. AI 改变的是缺陷的「结构」，而不只是数量。 Apiiro 在 Fortune 50 仓库的观测：语法错误下降 76%、逻辑 bug 下降 60%，但权限提升路径上升 322%、架构设计缺陷上升 153%。旧门禁（SAST + 人工 diff）恰好对新增的这一类是盲的。
7. 多 Agent 是一个分布式系统问题，不是「多开几个窗口」。 隔离（git worktree / devbox）、编排（blueprint / workflow）、合并策略、可观测性四件套缺一不可；经验并行度上限在 3–5，超过后协调成本吃掉全部收益。
8. 上下文工程是 agentic 时代的内存管理，Harness 是新的性能杠杆。 Anthropic 归纳为「写 / 选 / 压 / 隔」四类策略；产业侧报告显示，同一模型换一套 harness，标准基准可差 3 个百分点以上。
9. 角色迁移是 Coder → Conductor → Orchestrator，但「可完全委托」仅 0–20%。 Anthropic 2026 趋势报告：约 60% 的工作流已含 AI，可完全委托的任务却不到两成。这是协作悖论，是稳态，不是过渡态。
10. 安全与治理必须内建在生成路径，而不是事后扫描。 AI 生成代码的漏洞率在不同口径下为 25.7%（522 样本 / 5 个 SAST）到 45%（100+ 模型 / 80 任务）；更棘手的是斯坦福实验发现的系统性过度自信——用 AI 的人写了更不安全的代码，却更相信它是安全的。

以下是 IBM 文章 《什么是规范驱动开发？》（What is Spec-Driven Development?） 的中文翻译：

作者： Anna Gutowska（IBM AI 工程师、开发者倡导者）

发布日期： 2026年5月19日

规范驱动开发的定义

规范驱动开发（Spec-Driven Development, SDD） 是一种软件开发方法论。在正式编码之前，团队需先编写并达成一份关于实现细节的详细规范（Specification）。换句话说，这份规范将作为“构建什么”以及“如何构建”的唯一真实来源（Single source of truth）。

随着 Microsoft GitHub Copilot、Anthropic Claude Code 或 IBM Bob 等 AI 工具与编程助手的普及，生成代码的门槛已大幅降低。基于先进 AI 模型的 LLM 驱动型 AI Agent，只需用户输入一条自然语言提示词（Prompt），即可随时实时运行一系列迭代任务。

对于软件开发而言，这意味着我们可以优化并自动化构建原型、新功能、单元测试等的开发工作流。生成代码从未如此简单。然而，“氛围程序员”（Vibe Coders）需要警惕一个潜在风险：AI 的表现上限完全取决于它所接收到的指令质量。

技术债务的抬头：一个典型场景

你可能在现实世界中见过技术债务，甚至自己都没意识到。

随着 Cursor、Claude Code、Windsurf 以及 OpenClaw 等 AI Coding Agent 深度嵌入日常开发工作流，软件开发正在经历从 “人类编写代码” 到 “人类定义规则，Agent 协作编码” 的转变（Agentic Engineering）。

我们在项目中往往会编写 README.md 面向人类开发者，但很多团队忽视了为 AI Agent 提供一套上下文感知与行为治理规范（Harness Guidelines）。这就是 AGENTS.md（或 AGENT.md / CLAW.md）存在的意义——它是写给 AI Agent 看的“项目运维与开发指南”。

本文以实际项目架构为例，聊聊为什么需要 AGENTS.md 以及如何为你的开源或商业项目定制一份高效的 Agent 治理规范。

一、 为什么传统的 README.md 不够用？

人类开发者阅读 README.md 时，拥有强大的泛化能力和隐式背景知识；但 AI Agent 在读取代码库时，是以 Token 上下文的形式载入信息的。

传统的 README 往往面临以下痛点：

• 信息密度不匹配：包含大量面向用户的推广语言、演示 GIF 或过于冗长的安装介绍，浪费 Agent 有限的 Context Window。
• 缺少隐式约束：Agent 无法从普通 README 中感知“不要在组件里直接写 Raw SQL”、“修改 Schema 后必须生成 Migration”等团队内部约定的代码禁区。
• 缺乏验证门禁：Agent 在修改完代码后，往往不知道调用什么 CLI 命令来进行类型检查（Typecheck）和单元测试，导致提交带有隐式 Bug 的代码。

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 个并发）。支持增量更新 — 仅重新分析自上次运行以来发生更改的文件。

创建项目

# 🎮 坦克大战 - Tank Battle

一个经典坦克游戏克隆，致敬任天堂的《坦克大战》（Battle City）。

## ✨ 功能特性

### 核心玩法
- **玩家坦克** - 使用 WASD 或方向键控制移动，空格键射击
- **AI 敌方坦克** - 自动移动和射击，难度随关卡递增
- **基地保护** - 保护你的金色基地不被敌人摧毁
- **关卡系统** - 通关后自动进入下一关，敌人越来越强

### 地图元素
- **🧱 砖墙** - 可被子弹破坏，提供战术掩护
- **🔩 钢墙** - 不可破坏的坚固障碍物（增强子弹可以破坏）
// ...

一、理解需求

1. 需要游戏房间创建功能，支持生成唯一的游戏会话标识，用于管理单局游戏的生命周期
2. 需要玩家状态初始化功能，支持在游戏开始时设定玩家的初始生命值为3、初始分数为0及初始坦克属性
3. 需要玩家坦克移动逻辑处理功能，支持根据移动指令计算坦克下一帧坐标，并校验与砖墙、钢墙、水域、边界等地图元素的碰撞情况以阻断非法移动
4. 需要玩家坦克射击逻辑处理功能，支持根据射击指令生成子弹对象，判定子弹飞行轨迹与地图障碍物、敌方坦克及基地的碰撞结果
5. 需要地图数据加载功能，支持根据关卡ID获取对应的地图布局数据，包含砖墙、钢墙、水域、树林、基地等元素的位置坐标信息
6. 需要敌方坦克AI控制功能，支持自动控制敌方坦克进行移动路径规划、转向逻辑及自动射击，并实现随关卡递增的难度参数调整
7. 需要子弹碰撞判定功能，支持区分子弹击中不同目标（砖墙、钢墙、坦克、基地）后的处理逻辑，包括销毁子弹、扣除目标生命值或销毁目标
8. 需要基地保护判定功能，支持监测基地是否被敌方子弹或玩家误伤击中，一旦击中立即触发游戏失败结算流程
9. 需要地图元素破坏机制功能，支持普通子弹破坏砖墙、增强子弹破坏钢墙的逻辑，并同步更新地图障碍物状态
10. 需要道具生成与掉落功能，支持在特定条件触发下（如消灭敌方坦克）随机生成速度提升、火力提升、护盾、生命、炸弹、冻结等道具实体
11. 需要道具拾取生效功能，支持玩家坦克拾取道具后触发对应效果，包括移动速度增益、射击属性增强、无敌状态、生命值增加、全屏敌人清除及敌人冻结状态
12. 需要道具效果时效管理功能，支持对速度提升、火力提升、护盾、冻结等具有持续时间的道具效果进行倒计时管理及状态自动清除
13. 需要分数结算功能，支持根据消灭敌方坦克的类型、数量及通关奖励计算并累加玩家当前得分
14. 需要生命值管理功能，支持玩家坦克被击毁时扣除生命值，并在生命值归零时触发游戏结束流程
15. 需要关卡进度管理功能，支持在消灭当前关卡所有敌人后判定通关，并自动切换至下一关卡或触发游戏胜利结算
16. 需要游戏状态流转控制功能，支持管理游戏从准备开始、进行中、暂停、结束等状态的切换逻辑
17. 需要游戏音效开关控制功能，支持接收客户端音效设置指令，维护当前游戏会话的音效开启或关闭状态
18. 需要游戏结算功能，支持在游戏结束或通关时生成包含最终得分、存活状态、通关关卡数等数据的结算报告

AI 编程的演进逻辑非常清晰：GitHub Copilot 作为插件，在传统 IDE 里为大众提供辅助；Cursor 则打破束缚，通过 AI 原生 IDE 实现了深度的体验跃迁；而 Claude Code 这类 CLI 工具，则是为追求极致自由与自动化的极客准备的——它摆脱了图形界面的繁琐，让开发者在命令行中，就能以‘操作指令’驱动 AI 完成从编码到部署的全流程。

AI 编程三剑客：时间线与营收对比

维度	GitHub Copilot	Cursor	Claude Code
代表形态	IDE 插件 (Plugin)	AI 原生 IDE (Forked)	CLI 智能体 (Agent)
正式发布/爆发时间	2021年6月 (预览) / 2022年6月 (正式)	2023年 (起步) / 2024年底 (爆发)	2025年2月 (GA)
年营收 (ARR)	$20 亿+$ (2025年Q3数据)	20亿+∗∗(2025年Q3数据)∣∗∗10 亿+ (2025年底估算)	$10 亿+ (上线6个月即达成)
用户规模	2000万+ 开发者	100万+ 付费用户	爆发式增长中 (API驱动)
核心地位	行业标准与基建	效率工具的巅峰	自主编程的开端

1. GitHub Copilot：稳坐江山的“老牌霸主”

• 登基时间： 2021-2022年。它是 AI 编程的开创者，利用 GitHub 庞大的生态系统，迅速完成了从 0 到 1 的教育。
• 营收状况： 2025年 9月，微软在财报中确认 GitHub Copilot 的年经常性收入（ARR）已突破 20 亿美元。
• 现状： 虽然面临 Cursor 的挑战，但它依然是 90% 以上 500 强企业的标准配置。它的战略重心已转向 “代理化” (Agentic)，在 GitHub Universe 2025 上展示了全流程的 AI 协作能力。

• 提示词：使用 React 技术实现 Tic Tac Toe 游戏

• 运行游戏

• 创建新仓库

• 快速设置仓库

• 退出游戏

• 查看已安装的 MCP 服务器

• 创建新问题（issue）

• 查看 wang-junjian/tictactoe 项目中分配给我 issue，使用 GitHub MCP 服务器的工具 list_issues

• 当前仓库 wang-junjian/tictactoe 中有1个开放的 issue

• 分步实现 issue #1 玩家获胜时添加烟花效果

• 实现 issue #1 玩家获胜时添加烟花效果

• 运行游戏 - 获胜后的烟花效果

• 创建新问题 - Refactoring

• 创建分支 git switch -c Refactoring，对项目中的代码进行重构

• 完成代码重构

• 推送到远程仓库，git push -u origin Refactoring

• Compare & pull request

• 创建拉取请求（pull request），关联问题（issue #2）

• wang-junjian/tictactoe 项目中分配给我的 PR，使用 GitHub MCP 服务器的工具 get_pull_request

• 使用 GitHub MCP 服务器的工具 get_pull_request_files 获取 PR 的变更文件列表

• 完成 PR #3 的代码评审

• 使用 GitHub MCP 服务器的工具 add_issue_comment，提交代码评审