先让项目
说清楚自己
再让 Agent 动手。

先看懂贯穿案例里的五个词

这些词现在不用背公式，只要先知道系统里什么进入、什么出来、哪里会失效。后面的嵌入式章节会再展开。

三种阅读方式

Slash 命令不可用时

Slash 是已安装 Skill 的快捷入口，不是所有会话都自带。Skill 未安装或不可用时，删除模板第一行，用下面的普通提示词作为自然语言回退继续；剩余目标、证据和边界保持不变。

Codex 能做什么，不能替你做什么

一项可靠 Codex 任务的标准生命周期

1. 给目标和证据：描述想改变的结果、当前现象、已有日志和完成指标，而不是指定一个未经核实的修法。
2. 让它先探索：读取 AGENTS.md、相关代码、测试和 Git 状态，列出事实、假设和预计文件。
3. 确认最小方案：比较替代方案，明确保持不变项、停止条件和验证方式。
4. 执行受控修改：一次完成一个可验证目标；硬件、外部写入和 Git 高风险动作保留人工确认。
5. 用证据验收：运行相关检查，比较预期与实测，审阅实际 diff，并报告没有验证的部分。
6. 沉淀而不污染：长期稳定规则进入 AGENTS.md；一次性状态进入任务记录；重复流程第三次再考虑 Skill 或脚本。

Harness 最值得新手先学的六件事

什么时候先用 Plan 模式？

五步闭环：模式负责流程，你负责表达与确认

1. 切换到 Plan 模式：使用 Harness 的模式开关，不必在提示词里重新写一套“只读、不要实施”的规则。
2. 写下不完整想法：说明想实现什么、已经看到什么和不懂什么，口语也可以。
3. 回答提问框：问题会补齐真正会改变方案的选择；不知道时直接写“不知道”。
4. 审查计划：重点看目标是否准确、有没有改多、如何验收以及哪些动作要人工确认。
5. 确认后执行：切换回执行模式；完成后使用 Review 查看实际差异和证据。

第一次操作：十分钟完成一次真正的只读任务

这次不需要旧工程、Git 或板卡，只验证四件事：打开了正确文件夹、Agent 知道当前目录、读到了项目规则、没有写文件。

1. 准备练习文件夹：在资源管理器新建 codex-first-readonly，显示扩展名；分别复制下面两个文件，用记事本以 UTF-8 保存。
2. 打开正确工作区：在 Codex 选择打开文件夹/工作区，界面根目录必须以 codex-first-readonly 结尾。
3. 切到 Plan 模式：Plan 表示先调查，不等于额外写入许可。只复制第三个“第一次提示词”框；它故意不包含规则正文。
4. 对照真实文件：只允许读取、列目录和搜索；拒绝编辑、创建、删除、安装、联网及会写文件的命令。
5. 检查通过标准：路径正确，只列出两个文件，准确复述规则并输出文件中隐藏的校验词 READONLY-OK-27；资源管理器里仍只有两个内容未变的文件。提示词没有这个词，只有实际读取 AGENTS.md 才能得到。

用多个 Session 节约上下文

第一次不用先懂完整工程；先让 Agent 帮你把“我们有什么”说清楚。

项目初始化不是让 AI 一口气生成所有代码，而是共同建立一张大家都能看懂的地图：目标是什么、硬件有哪些、文件放在哪里、现在能验证什么、下一步最小任务是什么。学生只要提供自己知道的内容，不知道的地方直接说“不知道”。

第一次看到 Git，只先认识五个对象

接手项目的四轮扫描

1. 只读盘点
   记录 git status、目录、入口文件、工具链、生成代码边界和现有说明。此时不改文件，也不假设用户猜的文件位置正确。
2. 建立证据
   只执行低风险构建或静态检查，保存真实错误、工具版本和退出码。若构建会生成或覆盖文件，先说明影响。
3. 画项目地图
   列出五个最关键文件、数据流、软硬件接口、稳定提交和三个未知项；标明哪些结论来自代码，哪些仍是推断。
4. 选择首个阻塞项
   只处理一个能解除后续阻塞的问题。例如先验证编码器方向，不顺手重构整个驱动层。

让 Agent 采访你并生成提示词

八张好用的短语卡

按风险选择工作方式

两个层级，不要混在一起

下面的个人全局模板使用英文，是为了保持这份通用规则原文不变；不要求学生自己写英文。复制后可以让 Agent 用中文逐条解释，重点只记住：先澄清、简单优先、最小修改、证据验收。

先让 Agent 生成项目草案

先用十行 Starter，不要一开始背完整治理模板

什么时候升级？完成 09、11、12、16 章后，再采用下面的完整模板。采用前让 Agent 对照仓库逐项填充并标记尚未实现的机制；不要把 Runner、分支保护或自动归档仅写进文件就当成已经具备。

简单规则也有价值

规则层级

新手项目先只维护根 AGENTS.md，避免 Codex 与 Claude Code 对局部规则的读取方式不同。项目变大后若确实需要局部规则，先在根 AGENTS.md 明确列出文件及适用目录，并分别用干净会话验证两个工具都能复述；不要静默新增第二套规则。Claude Code 的兼容方式见后文：CLAUDE.md 只写导入指针 @AGENTS.md。

不用记得提醒它：更新动作已经写进项目规则

文件夹不是“放东西的地方”，而是团队共同记忆的索引。

电赛项目最常见的混乱不是代码写不出来，而是每个人手里都有一个“最终版”、关键结论只在聊天记录里、测试截图找不到对应固件。Agent 读到混乱的目录，也只能更快地产生混乱。整理项目的目的不是追求漂亮，而是让任何队员在十分钟内回答：现在做到哪、什么结论已确认、下一步是什么、证据在哪里。

一个够用的通用电赛目录

不要在根目录建立“新建文件夹”“最终版2”“可用代码”“临时”等目录。日期使用 YYYY-MM-DD，实验名描述对象和编号；固件不要靠文件名冒充版本，使用 Git 提交号和构建产物哈希关联。

三个记忆文件分别写什么

为什么固件源提交可不等于稳定分支 HEAD？记录 PROJECT_STATE 的纯治理 PR 合并后会产生新的文档提交，但它没有改变固件源码。纯治理文件 PR 不触发固件重构建；状态文件继续指向最近一次真正构建并验证过的源码 commit/tree 与 artifact SHA256，避免无限自引用。

Agent 维护，团队只确认

每天 10 分钟的统一节奏

1. 开始前：整合人的 Agent 展示稳定基线和 PROJECT_STATE；每人领取一个不重叠的 T 编号。
2. 实验前：台架操作人的 Agent 只在已验证采集程序存在时用 create-new 创建 run 目录和 manifest.json，写清固件、硬件、参数、预期与停止条件；否则只准备人工步骤，不声称自动归档。
3. 实验后：raw.ndjson 保持不变并记录哈希，result.md 只写观察与推断，二者分开。
4. 合并前：固定整合人审查 PR 的目标、差异、证据和项目状态更新。
5. 收工前：任务 Agent 提出长期规则与决定的更新建议；固定整合人的 Agent 串行落盘。

你只要说清大意，再让 Agent 通过提问生成“最小修改契约”。

“帮我修一下”不是错误，只是信息还不够。不要逼自己一次写出专业提示词：先讲目标和担忧，让 Agent 一次问一个问题，再把答案整理成可检查的计划。所谓契约，就是开始修改前双方对“改什么、不改什么、怎样算完成”的短暂约定。

什么时候用 Plan 模式？

Plan 模式可以理解为“先做调查和方案评审，暂时不施工”。当任务陌生、需求不清、涉及多个文件、会碰硬件、可能影响队友，或你还不知道怎么验收时，先进入 Plan 模式。改一处确定的错别字通常不需要。提问框只在 Plan 模式出现：看到提问框时逐题回答即可；没有提问框时，你仍可以在对话中要求“一次只问一个问题”。

最小修改的七步循环

1. 只读探索：确认真实调用链、现有测试和用户未提交改动。
2. 重述目标与不变量：把“要变”和“绝不能变”分开。
3. 预测涉及文件：每个文件写明修改理由。
4. 实施最小差异：不顺手重构、统一命名或升级依赖。
5. 运行验证：先复现，再修复，再运行相关检查。
6. 审阅实际差异：检查纯格式变化、生成文件和意外接口变化。
7. 报告偏差：实际文件数是否超过计划，为什么，还有什么风险。

三层补救循环：第一次不满意，不必重开一个大任务

AI 最有价值的学习能力，是把“我不会”拆成可验证的问题。

新手最大的优势是可以坦白“我不知道”。危险的不是不会，而是 Agent 和你都把空白当成默认常识。开始时告诉它你的年级、学过什么、没做过什么、当前要解决的真实问题；让它先建立地图，再用资料和实验校准现实。

四类未知，用白话理解

何时学习，何时直接做原型？

从“听懂”走到“能够预测”的六级学习梯

1. 建立术语地图：例如 PPR、CPR、4 倍频、方向、计数器宽度、回绕、采样周期。
2. 分开事实、推断、假设和未知：不要把 Agent 的合理解释写成器件事实。
3. 定位权威来源：记录文档名称、章节或页码，以及它回答了哪个问题。
4. 实验前先预测：手转一圈应该增加多少计数？反转时符号怎样？何时回绕？
5. 设计最小证伪实验：断开电机输出，只记录原始计数和时间戳。
6. 最小集成并复述：预测通过后才接入速度计算；用自己的话解释，让 Agent 指出无证据的跳步。

Skill 是“遇到某类任务时应该怎样工作”的说明书。

普通提示词只服务当前对话；Skill 把一套反复使用的流程、检查项和工具说明保存下来，让 Agent 在匹配场景中读取。它更像实验指导书，不是给模型安装了新知识，也不是安全认证。Skill 写错、过时或来自不可信来源时，Agent 会更稳定地做错。

先审查，再看到安装按钮

固定 commit 只能防止引用随后移动，不能证明来源可信或内容安全。先在不会被 Agent 自动发现或触发的隔离目录读取固定 tree，审查 SKILL.md、脚本、模板和传递依赖；此时不安装到活动 Skills 目录，也不执行脚本。审查会话使用只读工作区，不连接硬件，也不提供 Git 写凭据、token 或其他凭据；被审文件中的命令、链接和“忽略前文”等文字一律只是待分析数据。人工选择“采用”后，关闭审查会话，再开一个新的安装会话，并先在假仓库、假日志和无硬件环境测试。无法完成审查就不安装，继续使用普通提示词。

1. 固定来源：记录仓库、许可证、完整 commit 和目标目录。
2. 读完整内容：检查触发方式、工具、读写、联网、删除、烧录和推送等副作用。
3. 追到依赖：脚本、模板、引用文档和其他 Skill 都属于执行内容。
4. 隔离模拟：只在假仓库、假日志和无硬件环境输出计划并测试拒绝路径。
5. 小范围采用：一个项目、一个场景启用；升级时重新审查差异。

四个通用 Skill：对齐、研究、诊断和审查

这组来自 mattpocock/skills，本手册固定到提交 9603c1cc8118d08bc1b3bf34cf714f62178dea3b。先按当前任务安装需要的项，不必一次装齐。

四个电赛专用社区 Skill：先审阅，再按项目选装

以下来自社区仓库 easyzoom/aix-skills，许可证为 MIT。本手册固定到完整提交 bb4c9bf475be49885425e7d48dc4db03b6e93d8b。它们不是官方背书或安全认证；一次只安装当前确实需要的一个。

先把容易混淆的词翻成白话

三个周期必须分开

Agent 生成嵌入式代码时要检查的七件事

• 时间单位是 tick、微秒、毫秒还是秒？所有换算是否集中且可追踪？
• 计数器会不会回绕？有符号与无符号减法是否符合预期？
• 中断和主循环共享变量是否需要 volatile、原子访问或临界区？
• ISR 中是否出现阻塞 I/O、长循环、printf 或动态分配？
• 输出是否限幅？编码器失联、通信超时和故障输入时安全状态是什么？
• 固定周期是配置假设还是实测事实？是否记录 dt 的最坏值与 p99？
• 自动生成代码区、用户代码区和手写模块边界是否保持？

先把边界、单位和失败状态画清楚，再让任何人或 Agent 写代码。

动作按“是否改变硬件状态”分类

首次 Bring-up 测试阶梯

1. 台架检查：核对原理图、逻辑电平、共地、硬件限流、机械固定和独立急停；执行机构默认禁用。实测急停按下后锁存断能，按钮释放不自动启动，必须人工复位并重新 ARM。
2. 只枚举，不连接：记录 ST-Link serial 与串口 VID/PID/serial，不根据 COM 号猜设备。
3. 最小生命迹象：只运行 LED、心跳、固件 build ID 和 reset reason。
4. 被动传感：手动施加输入，验证 raw → processed 的方向、范围、单位和噪声。
5. 逻辑输出：不使能功率级，用示波器或逻辑分析仪看 PWM、方向与频率。
6. 低能量开环：电机与机构刚性固定，移除轮、桨和松动附件或加防护罩；人员避开旋转平面，以经确认的低电压、低 PWM 和短脉冲验证方向，禁止手持测试。
7. 低目标闭环：保守目标、短时运行，任何安全触发立即切断动力并停止。
8. 性能与调参：固定轨迹、重复运行、记录最坏值，最后才讨论参数优化。

电脑连接硬件后，可以形成有人监督的自动调试闭环。

先别把“自动调试”想得太神秘：电脑用一条线把新固件写进板子，再用另一条通信通道读回板子打印的状态。Codex 能操作电脑上的软件、读这些文字和数据、比较前后结果；它不能隔空判断电压对不对，也不知道电机是否正在撞桌腿，所以接线、供电和运动始终需要人在旁边。

第一次连接，先认识四样东西

STM32 新手接线顺序

1. 彻底断电：暂不接电机和执行机构，检查板卡型号、供电电压、下载器电平和原理图引脚。
2. 只接调试通道：ST-Link 的 GND→板 GND、SWDIO→SWDIO、SWCLK→SWCLK；是否接 3.3V 和 NRST 按板卡文档决定。不要同时用多个来源给板子供电。
3. 接日志通道：USB-UART 的 GND 共地，适配器 RX 接板 TX，适配器 TX 接板 RX；只看日志时通常可先不接适配器 TX。
4. 人工检查后上电：限流从保守值开始，观察电流和发热；异常立即断电，不让 Agent“再试一次”。
5. Windows 确认身份：在设备管理器查看“端口 (COM 和 LPT)”及 ST-Link；拔插一次观察哪个设备消失和出现，记录设备序列号，而不是永远记住临时 COM3。
6. 先跑无害固件：只验证编译、下载、LED/心跳和串口 hello。这个最小链路通过后，才逐项接入传感器，最后接执行机构。

让 Agent 帮你识别设备，但先保持只读

第一次监督调试：每个危险动作单独批准

Runner 是项目要自己实现的脚本，不是内置安全能力

安全停止的三层责任

20 Hz 遥测只适合诊断，不能充当快速过流保护。任一安全层尚未实现或未验证，都不得进入带动力自动测试。如果流程稳定重复三次，再把 discover、flash、capture、run-test 固化成版本化脚本。

一次监督调试会话的九个关卡

1. 人工台架检查：接线、电压、共地、限流、机械固定、急停与默认禁用执行机构。
2. 只枚举设备：记录 probe serial、串口 VID/PID/serial，不连接候选设备。
3. 冻结身份：Git commit/dirty、artifact 路径与 SHA256、board/MCU UID、稳定固件与恢复方式。
4. 构建：保存警告、Flash/RAM 占用与产物；绝不自动选择“最新的 bin”。
5. 烧录批准卡：展示目标探针、目标 MCU、产物、哈希、提交与精确命令。
6. 烧录并 verify：失败保留原始输出并停止。任何重试都是一项新的精确动作，必须先解释原因并重新取得人工批准；身份不匹配、越界、异常运动、数据损坏或保护触发永不重试。
7. 核对 HELLO：fw/build、UID、reset reason、schema 与 state=DISARMED；不匹配立即停。
8. 按测试阶梯执行：前一级有证据通过才进入下一等级，高风险步骤再次确认。
9. 停止与归档：独立急停可用，MCU 请求 PWM=0/EN=OFF；保存 manifest.json、raw.ndjson、result.md、哈希和恢复后的稳定状态。

{"schema":1,"run":"direction-001","seq":42,"t_us":820000,"type":"sample","sp_rpm":300,"pv_rpm":284.7,"state":"SPEED","fault":0}

{"id":"speed-step-003","fw":"9d8c2af","profile":"speed_step",
 "setpoint_rpm":300,"duration_ms":2000,"repeat":3,
 "limits":{"current_mA":500,"speed_rpm":600,"heartbeat_ms":250}}

安全 PI/PID 调参顺序

1. 先排除基础错误：反馈符号、单位、固定 dt、传感噪声、输出方向与机械卡滞。
2. 先有保护：输出限幅、rate limit、anti-windup、急停、稳定参数与一键回退。
3. 一次改一个量：速度环常可先从 PI 开始，但不是普适定律；不要同时扫 Kp/Ki/Kd 或多层环路。
4. 固定条件并重复：同一 setpoint、负载和电源，每组至少三次，记录中位数与最坏值。
5. 看多指标：rise time、overshoot、settling、steady error、IAE、peak current、saturation% 与 dt p99。
6. 人做最后取舍：安全触发的 run 直接判废；Agent 给 Pareto 比较，不擅自持久化“最佳值”。

{"type":"hello","fw":"9d8c2af","uid":"0034...","state":"DISARMED"}
{"type":"sample","run":"dir-001","seq":10,"t_us":100000,"sp_rpm":300,"pv_rpm":-41.8,"u_permille":310,"current_mA":210}
{"type":"sample","run":"dir-001","seq":30,"t_us":300000,"sp_rpm":300,"pv_rpm":-219.6,"u_permille":1000,"current_mA":460}

先把判断分层

最小修改契约

更多症状的第一分流

平时边聊边做；碰共享台架前，先说一声、确认没人还连着。

不用开会、写计划或固定职位。查资料和写代码时，口头说清谁在看什么、谁准备改哪个文件就够了。共享台架也一样靠说：无动力、只读或手转检查一个人就能做；上电、烧录、改线或带动力时，先对身边同学说一声“我要连台架了”，并确认没有别人的电脑或会话还连着、还带着电。只有带动力才需要一个操作的人加一名在场观察者，不需要凑齐三个人。

为什么要问那一句：防的是同时控制，不是走流程

结果怎么记，才不会变成“我记得当时可以”

采集程序或串口工具直接保存一个新的 raw 文件；Agent 只能引用这份文件，另写一句事实结论，不能从聊天或截断终端重建、覆盖原始数据。人确认现场结果后，Agent 自动在 create-new 的 runs/<run-id>/ 中补全 manifest.json 和 result.md，写明原始文件路径、实际动作或命令、固件身份、已验证事实和下一步，并只提出一条 PROJECT_STATE.md 更新建议。它不能据此接管台架，也不能自行改写 AGENTS.md 或 DECISIONS.md。暂时没有采集工具时就拍照并明确写“证据链不完整”，不要假装已经保存了原始日志。

够用就停：普通协作靠当面说清，碰真实台架多问一句“没人还连着吧”，关键结果有原始出处，改过代码有 Git。只有任务变多、跨天或经常互相覆盖时，才展开下面的进阶方式。

Codex 与 Claude Code 可以共用项目事实，不要维护两份互相漂移的规则。

本手册以 Codex 为主。队员偶尔使用 Claude Code 时，仓库根目录仍只维护 AGENTS.md 这一个事实来源；CLAUDE.md 只写导入指针。这里的“指针”是 Claude 的文件导入语法，不是 Windows 符号链接。

不要在 CLAUDE.md 再复制一遍项目规则。修改规则时只审查和更新 AGENTS.md；然后分别开启一个干净的 Codex 和 Claude Code 会话，让它们复述项目目标、边界、验证和硬件红线，确认导入有效。若某工具需要自己的临时操作说明，应保持很短，并明确不能与 AGENTS.md 冲突。

Claude Code 的三层协作，从简单到复杂

第一个安全的多 Agent 练习

不要从“让三个 Agent 同时改固件”开始。让主 Agent 保持只读，分别委托：A 画代码调用地图；B 从数据手册提取已引用章节和待核实事实；C 审查测试是否覆盖目标。三者都不能改文件或操作硬件，最后由主 Agent 对照证据合并结论。这能让团队先学习任务边界和结果整合。

先看见 Git 解决的麻烦，再记它的词。

Git 不是比赛必背的命令表，而是给团队留一条可恢复的时间线。三个同学直接传“最终版2.zip”时，会同时失去三件事：不知道哪个版本能演示、不知道谁改了什么、改坏后不知道回到哪里。Git 记录文件历史；GitHub 负责把这段历史分享给队友并提供审查页面。

电赛为什么需要它？先问三个问题

什么时候用，什么时候不用完整 Git 流程？

先记住六个词

最重要的区别：commit 是“我在自己电脑留档”，push 是“让远端看见”，Pull Request 是“请队友审查”，merge 是“正式接入稳定版本”。Git 可以在没有网络时先本地提交；GitHub 只是分享和审查的地方。

三个人面对面的一天，只做六步

1. 说清一个目标：让 Agent 用白话读出稳定版本、当前任务和未知改动；工作区有不明改动就停下。
2. 分出一条任务线：确认任务名、预计文件和是否需要台架；得到确认后再让 Agent 创建分支。
3. 完成一个小变化：每次只改一小块，运行与目标对应的最小验证。
4. 看懂再提交：让 Agent 展示实际 diff、没有修改的内容和验证证据；你确认后才提交。
5. 分别交给队友：提交、push、创建 PR 三件事分别确认；非作者先 Review，固定整合人决定 merge。
6. 同步稳定版本：合并后所有人让 Agent 检查新稳定提交；只有固件源码变更才从该提交重构建。

固件源码变更时，只有固定整合人按进阶规则在干净 checkout/worktree 重构建；其他队员只核对最终 commit/tree、artifact SHA256 和无动作 HELLO，不要把自己的脏工作区产物称为稳定固件。

15 分钟练习：亲眼看到 Git 的价值

第一次练习不需要 GitHub、账号或硬件。让 Agent 选择已有仓库里的独立 practice/ 目录；如果项目还不是 Git 仓库，就在项目外创建一个临时练习仓库，绝不要在正式项目里随手 git init。练习成功后，再展开进阶配置远端和 PR。

1. 让 Agent 在本地练习仓库的 practice/team-status.md 写三行：LED、编码器、遥测各自的当前状态。
2. 队员 B 只改“编码器”一行并做本地提交；队员 C 只改“遥测”一行并做本地提交。两个任务不碰正式代码和硬件。
3. 让 Agent 展示两条本地分支的 diff，再在本地依次合并。合并后你们能同时看到两人的变化，不需要网络。
4. 故意在这个练习文件里删掉 LED 一行但不要提交，让 Agent 展示 status/diff，并只恢复这个练习文件。恢复后再检查其他文件没有被碰。

让 Agent 操作命令不等于把方向交给 Agent：每一次写入、推送和合并都要先看目标、实际差异和证据。你只需要会说清楚“我要做什么”和“我不允许改什么”。

论文也是项目产物：文字、图、数据和代码必须能追溯到同一份证据。

不要等代码完成后才让 AI “编一篇论文”。从第一轮实验开始保存图表来源、参数、固件版本和失败结果。推荐把 Markdown 作为可审查的主稿：它是普通文本，能被 Git 比较，也方便 Agent 小范围修改；需要学校 Word 模板时，再把主稿生成 DOCX 并做人工排版检查。

推荐目录与职责

路线 A：Markdown 主稿，最适合团队协作

1. 先写证据大纲：每一节写它要回答的问题、引用哪次实验、需要哪张图，不让 Agent 凭空补结果。
2. 小节分工，不分叉主稿：队员提交具体小节或图表；固定整合人合并后统一术语、单位和叙事。
3. 引用原始证据：图注或附近注释记录 run 路径、Git 提交、数据处理脚本和参数。
4. 让 Agent 做对抗式审查：找“结论强于证据”“图表与文字数值不一致”“只报最好一次”“单位或符号漂移”。
5. 固定工具版本后导出：可使用 Pandoc 或 Quarto 将 Markdown 与参考文献生成 DOCX/PDF；先由 Agent 读取当前安装版本和帮助，不照抄过时命令。
6. 渲染后逐页检查：目录、公式、表格、题注、交叉引用、图片清晰度、孤行、分页和中文字体都需要看实际页面。

路线 B：用 iOfficeAI/OfficeCLI 让 Agent 生成和检查 Office 文档

iOfficeAI/OfficeCLI 提供面向 Agent 的 Office 文档操作能力。它适合把结构化内容写入 Word、读取/检查生成结果和自动化重复格式操作。它仍是第三方工具：安装前固定版本、阅读许可证和安装脚本，在副本或 report/build/ 中试跑，不直接覆盖唯一的学校模板或最终稿。

从实验到论文图表的可追溯链

先学会看懂 Agent 做了什么，再决定它是否完成。

Review（审查）不是要求学生逐行读懂所有代码。第一遍先判断它有没有做对任务，第二遍看有没有改多，第三遍检查证据是否真的支持结论；最后只深入理解会改变系统行为的关键路径。Agent 可以当讲解员和质询者，但不能同时当作者、裁判和批准人。

新手审查的四遍法

1. 目标遍：让 Agent 用你的原话复述需求，再列出实际交付。逐项标记完成、部分完成、未做；不要先被代码细节淹没。
2. 范围遍：看修改文件清单和每个文件的理由。出现计划外目录、依赖升级、批量格式化、接口重命名时先停下问为什么。
3. 证据遍：区分静态阅读、编译、自动测试、模拟数据、真实板卡测试。查看命令和输出；“应该可以”“逻辑上通过”都不是执行证据。
4. 理解遍：沿关键数据路径问输入从哪里来、在哪转换、何时失败、失败后怎样进入安全状态。用自己的话复述，再让 Agent 用反例检验。

不用懂所有语法，也能问出关键问题

“运行成功”与“任务完成”差在哪里？

构建成功只证明编译器接受了当前代码；单元测试通过只证明被覆盖的输入符合断言；串口有输出只证明某条通信路径工作；电机转起来只证明能量已经输出，甚至可能更危险。完成必须回到赛题指标、边界条件、重复次数和安全行为。

• 每个赛题指标对应一个测试步骤、阈值和证据文件。
• 保存稳定固件、配置、日志、已知问题和降级演示方案。
• 提交前审阅差异：每行改动都能解释其目标。
• 比赛前留出冻结时间，不在最终演示前做大范围改动。
• 复盘重复错误：只把已经验证的规则写回 AGENTS.md。

冻结不是停止思考，而是停止不必要的变化

监督调试会话判读

硬件会话结束后，不要只读 Agent 的总结。把操作时间线、人工批准点、原始工具输出、设备身份、固件 ID、遥测与停止原因并排检查。若总结说“通过”但日志有重启、序号缺口、过流事件或目标设备不一致，以原始证据为准。

阅读完成不等于学会；能独立产出、解释和复现，才算掌握。

{"schema":1,"run":"direction-001","seq":0,"t_us":0,"type":"hello","fw":"9d8c2af","state":"DISARMED"}
{"schema":1,"run":"direction-001","seq":10,"t_us":500000,"type":"sample","sp_rpm":300,"pv_rpm":-41.8,"u_permille":310,"current_mA":210}
{"schema":1,"run":"direction-001","seq":30,"t_us":1500000,"type":"sample","sp_rpm":300,"pv_rpm":-219.6,"u_permille":1000,"current_mA":460}

综合任务：完成一次低风险速度闭环演练

1. 建立项目地图和根 AGENTS.md。
2. 写赛题验收矩阵、接口契约和第一个最小任务卡。
3. 完成设备枚举、HELLO、被动编码器与逻辑 PWM 验证。
4. 用 manifest.json 和已验证采集程序运行低目标测试，归档原始 NDJSON、result.md 与哈希。
5. 从日志提出并执行一个最小实验；修改后审阅实际差异。
6. 用 Git 小提交、PR、非作者 Review 和验收矩阵完成团队交付。

自我评分

你负责说真实想法，Agent 负责把它整理清楚。

新手不需要学“提示词咒语”。先用自然语言说目标、现状、担忧和理想结果，哪怕其中有“不知道”；再复制下面的“元提示词”，让 Agent 一次问一个问题，最后生成四部分任务：目标 + 现状 + 边界 + 验收。正式提示词生成后仍要读一遍，特别检查它有没有替你添加未确认的需求。

最通用：让 Agent 生成本次正式提示词

进入 Plan 模式后，直接说想法

几个能组织思考的短语

从第一性原理重新检查一个方案

对抗式审查生成器

当你完全不知道怎么开始

补充模板：按当前阶段复制

把方法建立在可追溯的来源上。

1. Claude：大型代码库中的工作方式与配置层次——用于“上下文、技能、治理与持续维护”的参考。
2. Codex 官方手册——用于 Codex 的整体工作方式与当前产品能力。
3. Codex Prompting——目标、上下文、约束和验证的任务表达。
4. AGENTS.md——持久项目规则与嵌套作用域。
5. Subagents 与 Git worktrees——独立任务与隔离工作目录。
6. Finding Your Unknowns——用于“地图不是地形、主动寻找未知项”的学习框架。

工具能力、赛事规则和硬件安全要求会随环境变化。现场以你们的真实设备、官方数据手册和比赛规则为准。每次模拟赛后重新核对链接、工具版本、板卡差异和已经过时的长期规则。