Separating rules, documentation and context

Back to the Codex learning hub

Goal and preparation

Not every document belongs inside AGENTS.md. Rules hold durable work requirements; README helps people find entry points; design notes specify a feature; handoffs record current progress and next actions. Links among ordinary Markdown files do not automatically load every document. State when to read each source in rules or the task, then verify the files were actually consulted.

Step 1: Prepare a complete project copy

Extract the Small Steps pack, copy expected to codex-docs-lab and retain the original. Use expected, not broken: this exercise identifies an outdated handoff hypothesis rather than repairing the filter again. Confirm index.html, style.css, app.js, core.mjs and core.test.mjs at the root, then add docs.

The following four samples are complete files for the stated paths. If your copy already contains one, preserve and merge its content rather than overwriting important guidance. Shared English samples make filenames, links and criteria comparable across all five editions; your own documents may use your preferred language.

Step 2: Write rules and entry points

Write root AGENTS.md below. It directs filter work to docs/filters.md and resumed work to docs/handoff.md, then requires checking old notes against code and execution. That avoids treating a previous hypothesis as fact. It neither loads every design for every task nor grants tool permissions.

# 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.

Root README.md gives purpose, file roles and the test entry point. Its two links should open real files under docs. Relative links help readers and editors but do not prove Codex automatically expanded them. Use the first project walkthrough for preview setup, and do not invent an npm test entry point for this package-free project.

# 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.

Step 3: Separate requirements from execution records

docs/filters.md states verifiable requirements. Read completed and Build incomplete provide fixed inputs, each filter has an explicit output, and an empty list supplies a boundary. This describes how the feature should work, not what this computer has tested. Order and nonmutation constraints remain visible when assessing a change.

# 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 deliberately retains an unverified old hypothesis: Completed may return unfinished tasks. Because this starts from expected, the next task should check and reject that hypothesis rather than break working code to follow a note. Identify the source version. This exercise uses an expected copy and subsequent file/test evidence; a real Git project can also record its 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)

Before verification, copy these four new documents to a backup folder outside the project, preserving their relative paths. Compare the five source files with the untouched expected copy. Afterwards, only docs/handoff.md may differ. Make sure any editor comparison uses this backup, not an older task's files; Git is not required to compare two real files.

Step 4: Verify the documents in a fresh task

Save all files and start a fresh desktop task or CLI session in codex-docs-lab. Submit the request below, authorizing only handoff.md edits while preserving source, tests and rules. If read-only permissions prevent that update, collect and verify the read/test results, then update the note manually or adjust the specific permission scope using the permissions lesson.

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.

A valid result identifies the current correct completed predicate, three passing core tests and a rejected stale hypothesis. Verified records actual commands, outcomes and relevant files; Pending retains the unperformed browser check. README and filter requirements stay unchanged. Defining a browser check does not mean it passed. Independently run the command below and verify only handoff.md changed.

node --test core.test.mjs

Make the handoff traceable

Fill the fields below from your output in the appropriate handoff.md sections; unresolved brackets are not a completion record. If Node is unavailable, tests fail or no run occurs, keep the hypothesis unresolved with the reason. Reading code supports code inspection, not a claim of executed tests or browser use.

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]

Failure exercise, restoration and maintenance

To practice a missing design document, preserve handoff.md and filters.md, rename the latter to filters.saved.md and request the original path in a fresh task. Expect an explicit missing-file result and path/directory checks, not invented evidence from old chat. Restore the name and verify README's ./docs/filters.md and the document's ../README.md return link.

When documents conflict, identify product requirements versus historical hypotheses and align with the current explicit task. Do not silently rewrite all documents to conceal the discrepancy. Shorten oversized rules by moving duplicate background/logs while retaining specific reading triggers and valid links. Refresh handoffs after actual verification, with pending work, rather than pre-filling success at task start.

To repeat, restore only your saved handoff.md to its initial unverified state and keep correct code. The four documents affect this lab, not global settings. Completion means valid files/links, distinguished rules/history, sourced test results, detected missing files and no invented passes. The samples are original and rule discovery is documentation-checked. Locally passing expected tests are not proof of each reader's Codex execution.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex