实践记录：在上一篇里，我用 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 就是围绕这张表设计的。

摘要：在 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

文档即代码（Docs-as-Code，或 Documentation-as-Code）是一种将软件开发的最佳实践应用于技术文档编写与管理的理念和工作流。

它的核心思想是：像对待源代码一样对待文档。

核心运作方式

在传统模式下，文档通常在 Word、Confluence 或在线 Web 编辑器中撰写和发布。而在 Docs-as-Code 模式下，文档与代码共享同一套开发工具链和协同流程：

维度	传统文档模式	Docs-as-Code 模式
存储格式	Word (.docx) / PDF / 数据库格式	纯文本轻量标记语言（如 Markdown、reStructuredText、AsciiDoc）
版本控制	文件名重命名（如 xxx_v2_最终版.docx）	使用 Git / GitHub / GitLab 进行粒度管理
协作方式	邮件发附件 / 在线协同文档评论	创建分支（Branch）、提交 Commit、发起合并请求（Pull Request/PR）
审核机制	口头/邮件确认	代码审查（Code Review），团队在 PR 中直接针对每一行批注
发布构建	手动导出或人工复制粘贴发布	自动化 CI/CD 流水线，结合静态网站生成器（如 Docusaurus、MkDocs、Hugo）自动构建并部署

Docs-as-Code 的四大核心优势

1. 与代码强同步，减少文档滞后 开发者在修改代码的同时，可以在同一个 Git 提交或 Pull Request 中顺便更新对应的文档，避免了“代码变了，文档忘记改”的问题。
2. 完备的版本控制与追溯 通过 Git 历史，可以清晰查到“谁在什么时间修改了哪一行文档，为什么修改（结合 Commit 信息）”，且可以随时回滚到历史版本。
3. 质量自动化校验 可以利用 CI/CD 流水线集成自动化工具：

• 拼写与语法检查（如 Vale、Grammarly CLI）
• 死链检测（自动检查 Markdown 中的链接是否失效）
• 格式统一（如 Prettier 自动格式化）