生活分享

规则、说明与上下文文件怎么分

把工作规则、专案入口、设计条件与交接状态分开保存,用实档与测试验证过期猜测。

阅读时间约 12 分钟 · 操作 25 分钟

原创流程示意图,非产品界面截图。
图片:Mokaair (© Mokaair)
回总目录:Codex 学习中心:完整教程目录

实践 · Desktop / CLI / VS Code / JetBrains / cloud

本篇目录
  1. 目标与准备
  2. 步骤一:准备完整专案副本
  3. 步骤二:写规则与阅读入口
  4. 步骤三:分开条件与执行纪录
  5. 步骤四:用新任务验证文件分工
  6. 故障练习、还原与维护

目标与准备

不是每份文件都要塞进 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;并要求用程式和执行结果验证旧纪录,避免直接把前人猜测当成事实。它不要求每个任务都读所有设计资料,也没有把文件变成工具授权。

档案内容:根目录 AGENTS.md · markdown
# 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 已自动展开读取。需要更多启动步骤可接回,不要把不存在的 npm test 写成入口。

档案内容:根目录 README.md · markdown
# 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 未完成是一组固定输入;每个筛选有明确输出,空清单则是边界案例。这份文件描述应该如何运作,没有声称这台电脑已跑过测试。资料顺序与不修改输入的要求留在设计条件,让修改功能时仍能判断是否破坏其他行为。

档案内容:docs/filters.md · markdown
# 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。

档案内容:docs/handoff.md 的起始未验证纪录 · markdown
# 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,但保留程式、测试与规则档不动。若目前唯读模式不能更新,先取得读取和测试结果,核对后由你手动更新同一份交接纪录,或依调整授权范围。

自然语言提示词:在新的文件练习任务输入 · text
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。

系统终端机:在 codex-docs-lab 根目录执行 · sh
node --test core.test.mjs

将交接改成可追查的结果

不要把下列方括号原封不动当成完成纪录;以你的输出填写并放进 handoff.md 的适当段落。若 Node 不可用、测试失败或未执行,就保留原本假说的未确认状态及原因,不填三项通过。读懂程式只能支持程式检查,不能代替执行测试或画面操作。

交接纪录栏位:填妥后整合到 docs/handoff.md · text
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 已完成执行。

原创流程示意图,非产品界面截图。
原创流程示意图,非产品界面截图。 · 图片:Mokaair (© Mokaair)
阅读完整文字说明

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 测试和浏览器操作验收,并留下可重新启动与还原的交接纪录。

  • 生活分享

    用量与效率:减少重工

    记录任务条件、模型选项、时间与成果,找出能减少无效重试和过多上下文的调整。

最新旅游情报攻略

资料来源

生活分享