摘要：在 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 自动格式化）

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)

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

HTML 版本

1. OpenSpec 是什么

OpenSpec 是一套规约驱动开发（Spec-Driven Development）的工作流工具。它要解决的问题是：在 AI 智能体参与编码的场景下，如何让"想清楚 → 写计划 → 写代码"这三个动作不互相污染，并且让代码之外还有一份可追溯的事实来源。

1.1 两种产物

产物	位置	回答的问题	生命周期
specs（规格）	openspec/specs/<capability>/spec.md	系统现在是什么行为（已交付、已归档的能力）	长期存在，随每次归档增量演进
changes（变更）	openspec/changes/<change-name>/	这一次要改什么（尚未实现的计划）	完成后整体移入 changes/archive/

一句话：specs/ 是唯一事实来源，changes/ 是待实现的增量，archive/ 是它是如何达成的历史。

关键差别在于 specs/ 是能力（capability）维度、changes/ 是变更维度。同一个能力会被多次变更反复修改，每次修改只写"增量"（delta），不重写整份规格。

1.2 五步循环

每个变更都走同一条闭环，本项目严格落在这条闭环上：

flowchart LR
    E["1 · Explore<br/>和智能体一起想清楚"] --> P["2 · Propose<br/>Agent 起草方案（不写代码）"]
    P --> R["3 · Review<br/>你修正方案"]
    R --> A["4 · Apply<br/>Agent 逐项构建"]
    A --> AR["5 · Archive<br/>增量写入 specs 并归档"]
    AR -. "下一次变更" .-> E

若渲染环境不支持 Mermaid，可读作线性流程：Explore → Propose → Rev

macOS 录屏视频压缩工具使用说明

本工具是一个专为 macOS 设计的自动化脚本，它能帮助您将录屏或大体积视频文件压缩为高兼容性、恒定帧率（60 FPS）的 MP4 格式，有效解决体积过大以及剪辑时的“音画不同步”问题。

该工具设计为通过 macOS 的“快速操作”或 Automator 工作流程来调用，从而实现便捷的视频压缩操作。

• 作为“快速操作”使用：
• 设置“快速操作”： 您需要将提供的脚本保存为 Automator 工作流程的“快速操作”。
• 打开 Automator 应用（在“应用程序” -> “实用工具”中）。
• 选择 “文件”>“新建”。
• 选择 “快速操作” 并点击“选取”。
• 在顶部设置中，将“工作流程收到当前”修改为 影片文件（或 文件或文件夹）。
• 在左侧的库中，搜索并拖动 “运行 Shell 脚本” 到右侧的工作流程区域。
• 在“运行 Shell 脚本”模块中，将“传递输入”设置为 “作为自变量”（至关重要，请勿选错）。
• 将本工具的完整 Bash 代码粘贴到“运行 Shell 脚本”的文本框中。
• 选择 “文件”>“存储”，为您的快速操作命名，例如 “压缩录屏视频”。

• 使用方法：
• 打开 Finder，导航到您要压缩的视频文件（如 .mov 或 .mp4）所在的文件夹。
• 选中您希望压缩的视频文件（支持单选或批量多选）。
• 右键点击选中的视频，在弹出的菜单中选择 “快捷动作”（或顶部的“服务”菜单）。
• 点击您刚才创建的快速操作名称 “压缩录屏视频”。
• 系统会弹窗或通知提示已开始处理，工具将自动完成转码，并将压缩后的新视频（文件名附带 _compressed.mp4 后缀）保存在原始视频所在的同一文件夹中。