2026-第三十四周

该周报主要为各个地方内容的汇总整理

技术

AGENTS.md 指南

• 📄 AGENTS.md 是控制 AI 编码助手行为的配置文件，过大或混乱会浪费 token、降低性能，甚至误导代理。
• 🧠 代理的“指令预算”有限（约 150–200 条），文件越大，有效指令越少，因此理想状态是尽可能精简。
• ⚠️ 过期文档会毒化上下文，尤其文件路径变化快；应描述“能力”和“概念”，而非固定结构。
• ✅ 根 AGENTS.md 只需包含：一句话项目描述、非 npm 的包管理器、非标准构建/类型检查命令。
• 🔗 使用渐进式披露：把语言专属规则（如 TypeScript 约定）放到独立文件，并按需引用；还可嵌套文档树或链接外部资源。
• 📂 利用子目录 AGENTS.md 管理 monorepo：根文件写全局概况，包文件写包专属约定，各层保持聚焦。
• ✂️ 重构时先找矛盾、提取核心、分组建文件、删除冗余/模糊/显而易见的指令。
• 🧭 添加内容前自问：是否每项任务都需要？否则放入独立文件、嵌套文档或技能中。
• 🚀 精简的 AGENTS.md 让代理更专注、维护更轻松，并能适应未来工具变化。

视觉回归测试：最重要却未运行的测试

视觉回归测试通过截图与基线对比，捕捉用户实际看到的 UI 变化。它弥补了单元、集成和 E2E 测试只验证功能、不验证外观的盲区，尤其在 AI 生成代码和频繁样式变更时尤为重要。文章介绍了其工作原理、适用工具、CI/CD 集成方式、常见坑以及如何根据现有技术栈快速上手。

• 📸 视觉回归测试的核心：对页面或组件截图并与基线图像对比，检测外观变化，而非功能逻辑。
• 🔍 为什么需要它：测试覆盖率 100% 不代表界面正常；CSS 加载失败、样式冲突、外部样式干扰等问题只有视觉测试能发现。
• ⚙️ 工作原理：在真实浏览器中以无头模式渲染，生成截图并与基线比较；变化需手动批准，无变化自动通过，合并后新截图成为基线。
• 🧩 能捕获的典型问题：组件一处修改影响其他引用处、CSS 变更、布局重叠、响应式问题、跨浏览器渲染差异、字体或图片加载失败。
• 🛠️ 主要工具：Percy（适合 E2E 全页截图，UI 完善）、Chromatic（基于 Storybook 组件截图）、Vitest Browser Mode（内置截图测试，但缺少管理界面）。
• 🔗 CI/CD集成方式：Percy可轻松嵌入Playwright/Cypress测试；Chromatic配合Storybook；Vitest Browser Mode 直接调用 toMatchScreenshot。
• ⚠️ 常见坑与对策：字体加载不稳定、动画导致截图位置不同、动态数据（日期、相对时间）引发误报；需等待页面加载完成、用 CSS 隐藏动态/动画区域，并选择性测试重要页面。
• 🚀 如何开始：已有 Vitest Browser Mode 直接用内置功能；使用 Storybook 则推荐 Chromatic；已有 Playwright/Cypress 或 Puppeteer 则选 Percy 最易配置。
• 💡 作者经验：曾靠它捕捉到 SVG 图标修改后 20 多处渲染异常，这类问题靠手工或常规测试几乎不可能发现。

Agent 代理人在哪里存在？

本文探讨 AI 代理真正“居住”的地方。作者认为代理并非运行在沙箱、模型或编排器中，而是存在于其状态（state）中。状态包括工作文件、记忆、结构化状态和来源信息，应整合到一个可 fork 的对象存储桶（如 Tigris）中。借助 copy-on-write fork，每次运行都能获得隔离、可回滚的世界，从而安全实验与并行。文章提供了具体实现 shim，并讨论了与传统架构的权衡。

• 🧠 代理的本质是状态：模型、harness、沙箱都可重建，唯独状态是唯一不可再生的部分。
• 📦 状态由四部分组成：工作文件、记忆（会话历史）、结构化运行元数据、provenance（运行前的世界快照）。
• 🗂️ 传统架构将状态分散在 Postgres、Pinecone、S3、Temporal 等多系统中，导致没有一致快照边界，无法整体回滚或 fork。
• 🔀 解决方案：将所有状态放入单一的 Tigris bucket，以键值命名空间组织，实现统一快照与 fork。
• ⚡ 每个运行使用一个 copy-on-write fork（零拷贝），可随时分支世界、合并或丢弃结果，成本极低，适合千级并发代理。
• 🛠️ 实现 shim：harness 中 fork bucket 并生成仅限 fork 的凭证；entrypoint 把沙箱绑定到 fork；MCP server 按 key 读写状态而无需拷贝。
• ⚖️ 权衡：放弃 SQL 查询能力，换取原子性和可 fork 性；若访问模式为 get/put/list，则利大于弊，可另建索引支持复杂查询。
• 🏝️ 沙箱快照只是机器照片，bucket fork 是世界分支；fork 可跨云、零 egress，是代理平台的真正隔离基础。
• 🧩 结论：代理生活在可 fork 的 bucket 中——可快照、可分支、可丢弃，才让代理值得信任并支持安全实验。

工具

dbmate

dbmate 是一个独立、语言与框架无关的数据库迁移工具。它使用纯 SQL 管理迁移，通过时间戳减少多人协作时的版本冲突，并把数据库迁移、回滚、状态检查与 schema 快照统一到一个轻量 CLI 中，适合多语言服务共享同一套数据库工作流。

• 🧩 与技术栈解耦：作为独立 CLI，可配合 Go、Node.js、Python、Ruby、PHP、Rust、C++ 等任意后端语言或框架使用。
• 🗄️ 数据库覆盖广：核心支持 PostgreSQL、MySQL、MariaDB、SQLite 与 ClickHouse；文档还提供 BigQuery，以及通过 PGAdapter 连接 PostgreSQL 方言 Spanner 的方式。
• 📝 直接编写 SQL：迁移文件用 -- migrate:up 和 -- migrate:down 划分升级与回滚逻辑，不引入额外 DSL。
• 🕒 时间戳版本：文件名采用 [version]_[description].sql，默认以时间戳作为版本，降低多人同时创建迁移时的编号冲突。
• ⚛️ 原子执行：支持事务的数据库默认在事务中运行整份迁移；遇到不能放入事务的 DDL，可用 transaction:false 显式关闭。
• 🧰 命令完整：提供 new、up、migrate、rollback、status、dump、load、create、drop 和 wait 等常用操作。
• 🔌 配置简单：默认从 DATABASE_URL 读取连接地址，并自动加载 .env；目录、迁移表与 schema 文件等设置也可通过参数或环境变量覆盖。
• 🚀 开发体验顺滑：dbmate up 可在数据库不存在时自动创建并执行待处理迁移；只想迁移现有数据库时则使用 dbmate migrate。
• 📄 自动维护 schema：迁移或回滚后会更新 db/schema.sql，便于在 Git 中审查结构变化，也可直接载入快照以快速初始化测试数据库。
• 🔀 兼顾分支协作：待处理迁移按版本顺序执行；开启 --strict 后，发现迁移将被乱序应用时会直接失败。
• ⏳ 适配容器启动：wait 或 --wait 会等待数据库服务就绪，可配置超时时间，减少 Docker 环境中的启动竞态。
• 📦 分发方式丰富：可通过 npm、Homebrew、Scoop、Docker 或单个自包含二进制安装，不依赖应用自身的运行时。
• 🧱 也可作为 Go 库使用：支持在 Go 程序中调用迁移能力，并可通过 embed 将迁移文件打进应用二进制。
• ⚠️ 使用边界明确：schema_migrations 只记录版本号而不校验文件内容，因此已执行的迁移应先回滚再修改；schema 导出还依赖对应的 pg_dump、mysqldump 或 sqlite3 工具。

其他

他们看不见的工作

在一次与外部数据平台架构师的会议中，作者意外发现对方能通过深入提问快速识别出平台设计的成熟度，而内部领导却认为“还没达到”。这促使作者反思：工程价值大多隐藏于技术决策和稳定运行背后，难以被直接看见。因此，技术领导者的关键职责不仅是构建优秀系统，更要把技术决策转化为组织能理解的业务价值，主动讲述工程背后的故事。

• 🧑‍💻 会议中，外部架构师通过一系列架构提问（如配置化、可复用加载框架、dbt 建模、解耦计算存储、独立编排、可迁移性）准确识别出平台的成熟设计，并坦言“你们已处于很好的状态”。
• 🏢 内部领导收到结论后却回应“我们还没到那一步”，同样一群人看同一平台却产生相反判断，根源不是技术能力，而是领导缺少对话中的上下文与决策推理过程。
• 🫥 优秀工程往往是“隐形”的：可靠性提升、流程顺畅、事故减少，这些成就渐渐变成组织默认的基线，工程努力因此被当作理所当然，甚至被遗忘。
• ⚖️ 技术决策的价值不在于工具本身，而在于其业务后果：YAML 降低接入成本、dbt 保持业务逻辑可移植、独立编排保留演进自由，这些才是需要被看见的成果。
• 🗣️ 工程领导者的核心职责之一是“翻译”：把技术名词转化为组织关心的风险、成本、灵活性与战略选项，让工程变得“可读”，而不是让每个人都成为工程师。
• 📊 组织只会基于“能看到的现实”做决策，因此不能假设好工作自己会说话；技术领袖需要主动讲故事，把隐藏的架构价值转化为被理解、被认可的成就。
• 🔁 作者最终将这次会议视为对自身领导力的反馈：外部人能比内部人更懂自己的平台，说明沟通出了偏差；建设伟大系统只是工作的一半，另一半是帮助他人理解它为什么伟大。

桌子的同一边

作为管理者，与直属下属开会时必须始终站在同一阵线，即使团队犯错也不能公开拆台。文章给出了具体应对策略、真实案例，并解释了为何这是荣誉与责任所在。

• 🤝 核心铁律：与下属开会时永远同坐一边，团队的表现就是你自身的延伸。
• 🚫 绝不落井下石：下属说错话或语塞时，你不能跟着批评或抱着手臂旁观。
• 🛡️ 不加入“审判”：当队友被追问卡壳时，别跟着发难；把问题记下来，留到会后单独辅导。
• ⚠️ 唯一例外：只有发生极端失当行为（如人身攻击或严重失态）时，你才可置身事外。
• 🎯 补救技巧：可优雅地接管话题、暂停该环节稍后回议，或说“我们还没准备好”并主动承担火力。
• 😬 极端情况：若下属违抗明确指示且表现崩溃，允许保持中立，但仅在你已准备辞退他时使用。
• 💬 明确表态：向团队承诺“若场面失控，我会引导对话”，传递清晰的支持信号。
• 📋 实战示例：为团队向严厉董事汇报做足准备——提供背景、预演、明确分工，并全程当“守护者”。
• 🏆 运动队启示：运动队输球后也绝不公开怪罪队友，因为指责队友并不能免除自己的责任。
• 😨 恐惧文化代价：公开甩锅会摧毁成员的补救可能，并制造影响未来表现的恐惧文化。
• 🤲 荣誉法则：守住同一侧桌子，是一种荣誉；优秀的人只愿与有荣誉感的人共事。

拖延症患者安慰自己的方法：如果拖延解决问题的时间足够长，或许别人就会帮你解决了。

-- claytonwramsey.com