Initialize useful project guidance

Understand the approach

AGENTS.md is a plain Markdown file for instructions that should outlive one conversation. The CLI /init command generates a starting scaffold in the current directory. In the desktop app or IDE, you can also ask Codex to draft project guidance from the files it inspects. This is a writing task with consequences: an inaccurate instruction can be repeated in every later task, so the generated draft needs review.

Begin with facts visible in the scratch repository. Identify the project purpose, the documented run and test commands, and the files that should not be modified routinely. If a command is absent, record the gap instead of adopting a familiar npm script. Add a small working agreement about checking results and preserving unrelated changes. A short accurate file is more useful than a long generic engineering policy.

Inspect any existing AGENTS.md before generating or replacing it. There may already be important local rules or another contributor’s changes. In this lesson, create guidance only inside the disposable practice project and leave your Codex home untouched. Once the file is reviewed, start a fresh session in that project and ask which instruction sources loaded. Discovery happens at session startup, so a stale session is a poor test of a newly written file.

Initialize from repository evidence

The starter already has useful instructions, so blindly running initialization risks replacing them. Draft into AGENTS.proposed.md first. Verify each path and command: checks.cjs exists, package.json does not, and WORK-NOTE.md must survive. Keep the original object-preservation contract.

After review, integrate into AGENTS.md and start a fresh session at the intended project. Ask for loaded source paths and the test command. In the optional CLI track /init generates a scaffold inside the current directory. It is a composer control, not a terminal command or proof that the scaffold’s assertions are true.

Review guidance like code

Read each sentence as a future instruction. Replace vague demands with observable expectations and verify commands against the repository. Keep task authority separate from build documentation. Improve the smallest relevant guidance file instead of duplicating policies globally.

Try it step by step

1. Confirm the scratch project root and check whether AGENTS.md or AGENTS.override.md already exists there.
2. Read README.md and the actual project configuration; distinguish verified commands from plausible but untested suggestions.
3. Use CLI /init, or ask for a project-local draft, then edit the result to remove unsupported claims and broad permissions.
4. Start a fresh session and request an instruction-source summary before delegating a small practice task.

A useful starting example

Illustration · adapt before use.

# Orbit Notes guidance
Read README.md, notes.cjs and checks.cjs before a search change.
The local verification command is node --test checks.cjs.
Preserve notes.json, checks.cjs and WORK-NOTE.md.
Return original note objects in their original order.
Report changed files and observed checks.

Check your result

• The new file is inside the intended practice project, with no overwrite of existing shared guidance.
• Every command or repository fact in the file has an inspected source or is explicitly marked unverified.
• A fresh session identifies the file as an instruction source and follows its relevant requirements in a real small task.

Common mistakes

• Running initialization from a parent workspace and unintentionally setting rules for unrelated projects.
• Keeping scaffold suggestions such as npm test when the project has no corresponding script.