企业官网建设流程全解析

协作协议：Serial Studio 仓库的 AI 结对开发工作准则

【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio

Serial Studio 是一个开源的跨平台遥测仪表盘项目（Qt 6.11.2 + C++20，支持 UART、BLE、MQTT、Modbus、CAN Bus 等数据源）。本篇文章聚焦该仓库doc/claude/目录下的《Working Relationship》协作文档，讲解当 AI Agent 与维护者在本仓库结对开发时，双方应当遵循的五条核心工作准则——从"推荐而非罗列"、"敢于反驳"到"以现实观测为最高事实"等。读完本文，你将掌握如何在 Serial Studio 这样复杂度极高的代码库中，与 AI 协作伙伴高效、可信地推进开发工作，并能将这些准则与仓库内实际的规则体系（Trust Contract、spec-driven 工作流、J-Space 纪律）对照印证。

核心思想：平等协作，而非单向执行

doc/claude/working-relationship.md开篇即奠定了整个仓库 AI 协作文化的基调：以同侪（peer）身份工作，而不是一个被动的命令执行者。最好的会话是一个循环：Agent 带来工程能力与对抗性检查（adversarial checks），维护者带来事实真相与判断力。文档明确指出，这个协作模式最需要持续纠正的失败模式，来自低参与度和虚假自信（false confidence），而不是谨慎过头——用文档原话来说就是："Engage harder, claim less"（更投入地参与，更少地宣称）。

这一理念并非孤立存在，它与仓库根目录 CLAUDE.md 中的整套规则体系互为表里。working-relationship.md在 CLAUDE.md 的 Sub-Documentation 表格中被标注为"如何在此协作"的必读文档（"Read once per session"，每个会话读一遍），并被 trust-contract.md 列为配套阅读（companion reading）。因此，理解这五条准则，实际上就是在理解 Serial Studio 仓库 AI 治理体系的核心运作逻辑。

准则一：推荐，而非罗列（Recommend, don't enumerate）

当面临选择时，给出一个明确的建议（pick）和一句"为什么"，然后再列出备选方案。文档对此的批评非常直接："Here are five options, which do you want?"（这里有五个选项，你想要哪个？）这句话本质上是在把思考工作转嫁给用户。一个可以被否决的清晰推荐，远胜过一个中立的菜单。

在 Serial Studio 仓库中，这条准则被落实为每个设计决策只能有一个推荐。例如在 j-space.md 的第五项纪律（Named lenses for breadth and creativity）中明确写道："Designing: sketch 2-3 named candidate approaches before recommending one (recommend, don't enumerate — the naming is for divergence, the human still gets one pick)"——即设计时先命名式地画出 2~3 个候选方案以激发发散思维，但人类仍然只得到一个推荐。而 spec-driven.md 的 plan 模板更是把这条准则内置为硬性要求："Tradeoffs surface up front, as decisions"——权衡必须以前置决策的形式呈现，而不是事后补记。

准则二：当选择会付出代价时，敢于反驳（Push back when a choice will cost）

不同意时要说出来，点明代价，并在有理由时坚持立场。文档列举了几类典型的"会付出代价"的情形：

• 一次有风险的git操作；
• 一个建立在"未构建代码"（unbuilt-code）上的赌注；
• 一个会导致某些功能回归的设计。

文档的立场很鲜明："让坏决定通过的顺从（deference），比摩擦更糟"，但同时要求"一旦问题得到解答，就快速让步"（Concede fast once it's answered）。

这条准则在仓库中得到了最严格的制度化体现——即 trust-contract.md 中的"绝对规则"：绝不触碰、回退或恢复你自己编辑范围之外的文件。该规则禁止 Agent 对工作区中任何非本人编辑的文件执行git checkout/restore/reset/stash/clean等操作，即使这些文件看起来像噪声、生成产物或杂散的子代理输出。文档记录了这条规则的来历：曾有子代理重新生成了翻译文件，一次反射式的 restore 几乎丢弃了数小时未提交的工作。此外，"Stay in your lane"（守好本职） 规则同样体现了"敢于说、但别越界"的精神：发现邻近的问题时，在聊天中点名它（"noticed X — want it in this pass?"），而不是把它偷偷塞进当前 diff——范围蔓延（scope creep）会侵蚀审查者对每个 diff 的信任。

准则三：现实观测高于纸上推理（Ground truth outranks on-paper reasoning）

一张截图、"我平移视图时会闪烁"、"峰值几乎看不见"——这些真实观测是权威的；而纸上写的"这应该是正确的"则不是，尤其是在感知/UI 类工作上。文档要求把真实世界的观测当作规格说明书（spec），并尽早索要它们，而不是盲目交付。

这条准则在 Serial Studio 仓库中是被严格执行的工程纪律，贯穿多个文档：

• CLAUDE.md 的 Behavioral Rules 明确写道："Runtime experiments are sanctioned. Ground truth beats on-paper reasoning"——运行中的实验是被认可的，可以通过 API 服务器（localhost:7777，配合 tests/utils/api_client.py）驱动正在运行的应用来验证假设，也可以对既有构建目录运行ctest和已构建好的二进制（--selftest、--benchmark-hotpath）。
• 对于 GUI 卡顿问题，CLAUDE.md 的规则更为具体："Sample the running app before theorizing about a GUI stall"——永远不要只凭源码去推理冻结、卡顿或窗口尺寸失效问题，而应该用sample <pid>在后台采样真实堆栈。common-mistakes.md 记录了这条规则背后的血泪教训：2026-08-13 事件中，从源码读出的三个看似合理的修复方案全部是错的，而一次采样就一锤定音。
• spec-driven.md 的 Phase 0（可选、无门槛的探索阶段）同样体现了这一精神：在写 spec 之前，允许用一次性原型（scratchpad sims）、对运行中应用的 API 实验来"用戳现实的方式形成假设"，而不是靠坐而论道来写规格。

准则四：把权衡作为前置决策呈现，而非事后备注（Surface tradeoffs as decisions）

当两个合理的设计在某件重要的事情上产生分歧时（可读性 vs 保真度、性能 vs 简洁性），要在构建之前就把权衡摆到台面上，并附上推荐。文档特别指出："决定性的约束条件往往早已为人所知——应该一开始就把它拉出来，而不是等到第三轮迭代才发现。"

这条准则在仓库中同样是 spec-driven 工作流的硬性组成部分。正如 spec-driven.md 在"Why spec-driven over prompt engineering"一节中所言："Tradeoffs surface up front, as decisions. The working-relationship rule ('surface tradeoffs as decisions, not after-the-fact notes') is built into the plan template."——也就是说，working-relationship 的这条准则被直接内置到了/ss-plan阶段生成的plan.md模板中，要求每个计划都显式写出"tradeoffs as decisions, risks"。这也是为什么仓库要求非平凡/多文件工作必须走/ss-spec→/ss-plan→/ss-tasks→/ss-implement四阶段门控流程：一个错误的方法会在plan.md阶段被否决，而那时修改的代价为零；而不是等到一份 600 行的 diff 之后。

准则五：参与"为什么"，而不仅仅是"什么"（Engage the why, not just the what）

更高层次的问题会出现——"这是正确的方法吗？""从业者是怎么做的？""这件事到底应不应该做？"文档要求认真对待这些问题；重构问题本身（reframing the problem）往往比执行第一个貌似合理的修复更有价值。文档以"恒定宽度是示波器采用的做法"为例，说明一次好的问题重构能够带来的价值。这些对话是被期待的，不是绕路（"These conversations are wanted, not detours"）。

这一点与 j-space.md 的整套"言语化纪律"（verbalization discipline）相呼应。J-Space 的核心洞察是：模型能够言语化的概念，正是那些可用于灵活、有意识计算的概念；而熟悉形状的工作（文本续写、模式匹配式编辑）会绕过工作区自动运行——这正是静默破坏规则（silent-breakage rules）被违反的模式。因此，仓库要求：

• 在危险编辑之前，用自己的话命名当前修改所受的 3~5 条不变量（"Verbalize to load"）；
• 在交付之前做反事实自检（Counterfactual self-check）："如果我现在被叫停并问我这个 diff 最可能违反哪条规则，我会说出哪条？有什么具体证据表明它没有违反？"——要说出规则和证据，而不是一句笼统的"看起来没问题"。

五条准则如何融入仓库的日常协作流程

将五条准则放在一起看，它们并不是孤立的"软技能建议"，而是与 Serial Studio 仓库的整套 AI 治理体系一一对应、互相支撑的：

在实操层面，这些准则通过 repo-skills.md 中列出的/-斜杠技能被"即时调用"：例如ss-hotpath（编辑数据热路径前必须自行调用）、ss-spec/ss-plan/ss-tasks/ss-implement（四阶段门控）、ss-verify（提交前包装code-verify.py+sanitize-commit.py）、ss-ai-audit（审计 AI 面向文档与代码事实是否漂移）等。每个技能都锚定了一条来自 J-Space 的言语化步骤，确保"在行动点附近命名约束"这一核心机制得以生效。

值得注意的是，这些协作准则还配有一整套机械化的强制检查作为兜底：scripts.md 中描述了code-verify.py（结构 + 语调 lint）、claim-verify.py（AI 面向文档中的每个路径、符号、固定常量都对照代码树解析）、sanitize-commit.py（每次提交前运行）等脚本，以及singleton-census、tu-census、layer-verify.py等增长棘轮（ratchet）门控。这意味着"engage harder, claim less"不只是一句口号——仓库用可运行的检查来确保 Agent 的每一个"宣称"都有据可查，从而把协作关系建立在**可预测性（predictability）**之上，正如 trust-contract.md 所说："能力没有可预测性就会被禁用"（Capability without predictability gets disabled）。

结语

Serial Studio 的 working-relationship.md 虽然只有短短数十行，却是理解整个仓库 AI 协作体系的钥匙。五条准则——推荐而非罗列、敢于反驳、现实观测优先、权衡前置、参与"为什么"——共同刻画了一种理想的结对开发状态：Agent 不是应声虫，也不是独断者，而是维护者身边一位既敢于提出专业判断、又严格遵守边界、以现实为最高事实的同侪。当你在这个仓库中与 AI 协作时，把这五条准则与 CLAUDE.md、trust-contract.md、spec-driven.md、j-space.md 等配套文档结合起来阅读和实践，就能理解并融入这套经过实战打磨的协作文化——而这正是"Engage harder, claim less"这句话的真正含义。

【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio