生活分享

規則、說明與上下文文件怎麼分

把工作規則、專案入口、設計條件與交接狀態分開保存,用實檔與測試驗證過期猜測。

閱讀時間約 12 分鐘 · 操作 25 分鐘

LINE 分享
原創流程示意圖,非產品介面截圖。
圖片:Mokaair (© Mokaair)
回總目錄:Codex 學習中心:完整教學目錄

實作 · Desktop / CLI / VS Code / JetBrains / cloud

本篇目錄
  1. 1. 目標與準備
  2. 2. 步驟一:準備完整專案副本
  3. 3. 步驟二:寫規則與閱讀入口
  4. 4. 步驟三:分開條件與執行紀錄
  5. 5. 步驟四:用新任務驗證文件分工
  6. 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.

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Codex 學習中心:完整教學目錄

    從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。

  • 生活分享

    Worktree 與多任務隔離

    Worktree 讓同一個 Git 程式庫有不同的工作目錄,各自承接不同分支。它適合讓兩項工作分開改檔,但資料庫、連接埠與外部服務仍可能共用,不能把檔案隔離當成所有資源隔離。

  • 生活分享

    實戰:製作小網站

    從 brief.md 規劃並製作 Small Steps 待辦網站,完成新增、完成、刪除、篩選與本機資料保存。將 HTML、CSS、資料函式、畫面事件與測試分開,以 Node 測試和瀏覽器操作驗收,並留下可重新啟動與還原的交接紀錄。

  • 生活分享

    用量與效率:減少重工

    記錄任務條件、模型選項、時間與成果,找出能減少無效重試和過多上下文的調整。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享