生活分享
规则、说明与上下文文件怎么分
把工作规则、专案入口、设计条件与交接状态分开保存,用实档与测试验证过期猜测。
阅读时间约 12 分钟 · 操作 25 分钟

返回 Codex 教学总目录Codex 学习中心:完整教程目录从安装、第一个任务到 MD 规则与进阶集成,规划 60 篇 Codex 教程、十个单元。按程度、平台、需求或命令搜索下一篇;尚未公开的教程会标示状态,方便安排学习路线。阅读全文
目标与准备
不是每份文件都要塞进 AGENTS.md。规则描述每次都要遵守的工作要求;README 帮人找到入口;设计文件保存特定功能的条件;交接纪录保存这次做到哪里与下一步。写在一般 Markdown 里的文字,不会只因为互相连结就全部自动载入。应在规则或任务中明确要求何时读哪份资料,并用实际档案确认。
| 档案 | 要保存的资讯 | 不适合塞进去的内容 |
|---|---|---|
| AGENTS.md | 何时读文件、测试与交付规则 | 完整历史聊天 |
| README.md | 专案目的、档案入口、启动方法 | 每次暂时失败的逐行日志 |
| docs/filters.md | 筛选输入、预期结果、保留条件 | 目前是否真的测过 |
| docs/handoff.md | 已验证、未验证、下一步 | 密码、长期通用规则 |
步骤一:准备完整专案副本
解压Small Steps 练习包,将 expected 复制成 codex-docs-lab,保留原副本不动。这次不用 broken,因为我们要练习辨认交接猜测已经过期,而不是再次修筛选。用编辑器开资料夹,确认 index.html、style.css、app.js、core.mjs、core.test.mjs 都在根目录,再新增 docs 资料夹。
以下四段都是完整档案内容,依序存入指定路径。若副本已经有同名文件,先保存原文再合并,不要覆盖原本的重要规则。共同范例使用英文,五语读者可比对相同档名、连结和判准;自己的正式文件可以使用熟悉的语言。
步骤二:写规则与阅读入口
先把下面内容写进根目录 AGENTS.md。它指定筛选任务要读 docs/filters.md、续接任务要读 docs/handoff.md;并要求用程式和执行结果验证旧纪录,避免直接把前人猜测当成事实。它不要求每个任务都读所有设计资料,也没有把文件变成工具授权。
# Small Steps working instructions
- Before analyzing or changing filters, read docs/filters.md.
- When resuming work, read docs/handoff.md and verify its claims against current files.
- Preserve the task data format, localStorage key, existing tests and unrelated behavior.
- Use node --test core.test.mjs for core behavior checks.
- Do not add dependencies or network requests for this exercise.
- Record actual test results separately from hypotheses and checks not run.
- Update docs/handoff.md only within the scope authorized by the current task.
根目录 README.md 则放专案用途、档案对照和测试入口。点下面的两个文件连结时,都应在 docs 底下找到对应档案;这些相对连结对人和编辑器有帮助,但不代表 Codex 已自动展开读取。需要更多启动步骤可接回第一个专案完成第一个小项目使用 Small Steps 待办网站的独立副本,修改主标题与背景色。辨识五个练习文件的用途,比对修改前后差异、核心测试与两种窗口宽度,确认原有功能及数据保留。阅读全文,不要把不存在的 npm test 写成入口。
# Small Steps documentation lab
A local todo app using fictional practice data.
## File map
- index.html: page structure and filter controls.
- style.css: presentation and focus styles.
- app.js: browser events and storage integration.
- core.mjs: task operations and filters.
- core.test.mjs: core behavior tests.
## Read next
- [Filter requirements](./docs/filters.md)
- [Current handoff](./docs/handoff.md)
## Check
Run node --test core.test.mjs from this folder with Node.js installed.
This command description is not a claim that tests have run.
步骤三:分开条件与执行纪录
docs/filters.md 写出可验证的条件。Read 完成、Build 未完成是一组固定输入;每个筛选有明确输出,空清单则是边界案例。这份文件描述应该如何运作,没有声称这台电脑已跑过测试。资料顺序与不修改输入的要求留在设计条件,让修改功能时仍能判断是否破坏其他行为。
# Filter requirements
Given Read is completed and Build is incomplete:
- All returns Read, then Build.
- Active returns Build only.
- Completed returns Read only.
- An empty input returns an empty result for every filter.
- Filtering preserves task order and does not modify the input.
Core checks: node --test core.test.mjs
Browser check: create both tasks, complete Read, and inspect all three filters.
[Back to project](../README.md)
docs/handoff.md 故意保留一个未验证的旧猜测:「Completed 可能回传未完成项目」。因为本次起点是 expected,下一次任务应查证并推翻这项猜测,而不是照笔记去改坏已正常的程式。交接应有可辨识的来源版本;本范例没有要求 Git,因此用 expected 副本与稍后的实档、测试证据确认,正式专案可再记 commit。
# Current handoff
Starting material: an untouched copy of the Small Steps expected folder.
Goal: verify the current Completed behavior before changing any code.
## Verified
No checks have been run for this copy yet.
## Unverified hypothesis
An older note suggested Completed might return unfinished tasks.
Treat this as a hypothesis, not an instruction to change the implementation.
## Next action
Read docs/filters.md and core.mjs, then run node --test core.test.mjs.
Record the actual result and which checks remain unperformed.
[Back to project](../README.md)
开始验证前,将这四份新文件另外复制到专案外的备份资料夹,保留相同相对路径;五个程式档则对照未动过的 expected 原副本。操作后逐一比对,只有 docs/handoff.md 可以改。若编辑器显示差异,先确认比较的是这次备份,而不是别次任务留下的文件;没有 Git 也能用两个实际档案比较。
步骤四:用新任务验证文件分工
储存全部档案,再从 codex-docs-lab 开全新桌面任务或 CLI 工作阶段,确认工作目录。送出下列要求,明确允许更新 handoff.md,但保留程式、测试与规则档不动。若目前唯读模式不能更新,先取得读取和测试结果,核对后由你手动更新同一份交接纪录,或依权限篇权限、沙箱、网络与密钥沙盒决定工具技术上能碰哪些档案或网路,授权政策决定什么时候需要询问。两层设定不能混为一谈:不显示询问不代表动作一定被允许,能读档也不代表可以写入所有地方。阅读全文调整授权范围。
Resume this documentation lab. Read AGENTS.md, README.md, docs/filters.md and docs/handoff.md. Check the handoff hypothesis against core.mjs and run node --test core.test.mjs. Do not change source code, tests or rules. You may update only docs/handoff.md with observed results, evidence, and remaining checks. Explain which document supplied requirements and which supplied unverified history. Do not mark the browser check as passed without performing it.
合格结果应指出 completed 条件目前正确、3 项核心测试通过,旧猜测已被目前程式与测试推翻。handoff.md 的 Verified 应列出实际命令、结果和相应档案,Pending 保留未做的浏览器验收。README 和 filters.md 的要求没有变;不能把「定义了浏览器检查」改写成「浏览器检查已通过」。你再独立执行下面命令核对一次,并看差异是否只有 handoff.md。
node --test core.test.mjs
将交接改成可追查的结果
不要把下列方括号原封不动当成完成纪录;以你的输出填写并放进 handoff.md 的适当段落。若 Node 不可用、测试失败或未执行,就保留原本假说的未确认状态及原因,不填三项通过。读懂程式只能支持程式检查,不能代替执行测试或画面操作。
Checked at: [time and timezone]
Working copy: [actual practice folder and starting material]
Requirement source: docs/filters.md
Historical claim: [the old hypothesis]
Code inspected: [actual file/function and observed behavior]
Test execution: [command, exit code, pass/fail counts / not run and reason]
Hypothesis outcome: [supported / contradicted / unresolved, with evidence]
Browser verification: [actual scope and result / not run]
Files compared: [actual comparison against the saved originals]
Next action: [remaining work]
故障练习、还原与维护
要练缺少设计文件的情况,先保存 handoff.md 与 filters.md,再暂时将 filters.md 改名为 filters.saved.md,开新任务要求读原路径。预期明确回报文件不存在,先查路径与目前目录,而不是凭旧聊天编造一份已读过的设计。把档案改回原名后,再核对 README 的 ./docs/filters.md 和文件底下 ../README.md 两个方向都可到达。
如果需求互相矛盾,先标出哪份文件谈的是产品条件、哪份只是历史猜测,再向目前任务的明确要求对齐;不要默默把全部文件改成一致而隐藏问题。若规则太长,先搬走重复背景与完整日志,保留触发阅读的短句与可用连结。若交接一直过期,把更新交接放在每次真正验证后,写明未完成事项,而不是在任务刚开始就先填成功。
重做时只把自己保存的 handoff.md 还原到起始未验证版本,保留正常程式;四份新文件只存在本练习副本,不影响全域设定。完成判准是四档齐全、双向连结可读、能分辨规则与历史、测试结果有来源、缺档会被指出,而且交接没有把未做事项标成通过。本文范例为原创,规则载入行为依官方查证;本机 expected 测试有实际通过纪录,仍不等同每个读者的 Codex 已完成执行。
返回 Codex 教学总目录Codex 学习中心:完整教程目录从安装、第一个任务到 MD 规则与进阶集成,规划 60 篇 Codex 教程、十个单元。按程度、平台、需求或命令搜索下一篇;尚未公开的教程会标示状态,方便安排学习路线。阅读全文
阅读完整文字说明
Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.
同主题延伸阅读
生活分享
Codex 学习中心:完整教程目录
从安装、第一个任务到 MD 规则与进阶集成,规划 60 篇 Codex 教程、十个单元。按程度、平台、需求或命令搜索下一篇;尚未公开的教程会标示状态,方便安排学习路线。
生活分享
Worktree 与多任务隔离
Worktree 让同一个 Git 程式库有不同的工作目录,各自承接不同分支。它适合让两项工作分开改档,但资料库、连接埠与外部服务仍可能共用,不能把档案隔离当成所有资源隔离。
生活分享
实战:制作小网站
从 brief.md 规划并制作 Small Steps 待办网站,完成新增、完成、删除、筛选与本机资料保存。将 HTML、CSS、资料函式、画面事件与测试分开,以 Node 测试和浏览器操作验收,并留下可重新启动与还原的交接纪录。
生活分享
用量与效率:减少重工
记录任务条件、模型选项、时间与成果,找出能减少无效重试和过多上下文的调整。
引用本文的文章
最新旅游情报攻略

攻略东京
东京住哪一区:新宿、上野、东京站、涩谷、浅草、池袋、银座七区比较,机场交通、住宿税、行李寄送一次看
东京住哪一区?用同一套标准比较新宿、上野、东京站、涩谷、浅草、池袋、银座七个区域:从成田、羽田机场怎么过来、有哪些线路、周边有什么、街区氛围、适合谁。附比较表与山手线示意图,以及 2026 年 9 月核实的东京都住宿税(2027 年 4 月改为 3%)和机场宅急便寄送行李的规则。
- 预算
- 酒店

攻略东京
东京交通票券怎么选:Suica/Welcome Suica、Tokyo Subway Ticket、JR Pass 值不值得买
第一次去东京,每人先用一张 IC 卡按次付费(Welcome Suica 免押金、有效期 28 天)。一天搭四趟以上地铁,再加买 2,000 日元的 Tokyo Subway Ticket 72 小时券;只玩东京、不去关西,买 JR Pass 一定不划算。用决策图比较 TOURIST PASMO、iPhone 里的 Suica、东京 Metro 一日券能搭什么、不能搭什么;价格于 2026 年 9 月核实。
- 交通
- 预算

攻略东京
东京迪士尼乐园、海洋攻略:票价、梦幻泉乡 Fantasy Springs、尊享卡 DPA 与预约等候卡怎么用,第一次去选哪个园区
东京迪士尼一日护照采用浮动票价,2026 年 9 月平日大多为 9,900 日元、周末为 10,900 日元,官网每天 14:00 开售两个月后同一天的门票;免费的优先通行卡已不在官网服务清单,缩短排队时间只剩付费的迪士尼尊享卡(每人每次 1,000 至 3,500 日元)。另有运营时间与 25 周年活动、预约等候卡与报名体验、梦幻泉乡如何进入,以及第一次去选乐园还是海洋;2026 年 9 月通过东京迪士尼度假区官网核实。
- 行程范例
- 亲子
资料来源
- Custom instructions with AGENTS.md · 查证日期:
- Prompting · 查证日期: