How to Write AGENTS.md Right: Lessons from OpenAI's GPT-6 Astra Spec

The article recounts a practical revision of AGENTS.md for an e-commerce system after studying OpenAI's September 11, 2026 blog post Rethinking skills and prompts for GPT-6 Astra (https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra). The author notes that the revision did not shrink the document — AGENTS.md grew from 17,764 to 19,320 bytes and DEVELOPMENT.md from 38,971 to 41,871 bytes — but reduced ambiguity by defining when a goal is considered clear, when runtime operations trigger, which file holds higher authority, and which commands are read‑only queries.

Case 1: Target repository does not require a fixed phrase

Old rule: Git branch, commit, or push operations on the configuration repository only executed if the user explicitly said "configuration repository." New rule: default "repository" means the business code repository; if the user provides a full configuration file path or names the target repository, the scope is fixed. When a filename could exist in multiple repos, context decides. The configuration repo is maintained directly on master; the business repo uses feature branches. If a task touches both, each repo's workspace, branch, diff, and pending commits must be verified separately — one repo's state cannot substitute for the other's. A single user confirmation can cover both repos when both repos, files, and change scope are shown together. Staging area must be checked before commit; all pending commits must be reviewed before push; out‑of‑scope commits must not be pushed. User instructions like "commit only" or "do not push" must be obeyed.

Case 2: Editing a config file does not equal restarting production processes

Old rule linked "modify configuration" directly to cache clearing, application service restart, and background worker restart. This was over‑broad: local edits on a feature branch looked like they required target‑environment deployment. New rule splits into two layers: (1) editing local files or feature branches does not trigger target‑environment deployment, cache rebuild, or process restart; (2) only when configuration is already deployed to the target environment are cache rebuild, process restart, and side‑effect API verification performed. Production cache rebuild, process restart, and side‑effect API verification still require explicit authorization. Verification must use the same container, code version, and runtime user as the API; CLI read‑only output cannot replace real requests and logs. Minimum verification must show parameters entering business logic, parsed configuration definitions, and actual outgoing requests. If configuration has not taken effect, do not re‑trigger approvals, payments, queue jobs, or callbacks.

Case 3: Test scope is governed by AGENTS.md

Project convention: AGENTS.md has higher priority than DEVELOPMENT.md; the latter is a process reference. OpenSpec owns formal spec structure, risk grading, validation, and archiving. Neither can expand test authorization. The revision makes "test execution scope follows AGENTS.md as sole authority" explicit. This is not a new minimum‑test rule — historical versions already required it — but aligns existing baseline with document hierarchy. Default: run only tests directly related to the current change. Cannot run full module, full unit suite, or default suite just because a module is important, changes are large, or confidence is desired. Expansion requires user authorization or entry into merge/release verification phase. Database safety baseline: all test DB connections must point to a one‑off isolated test environment via a unified test base class; multi‑connection tests must use that base class. Before running tests, schema DDL, or migration verification, the runtime environment, actual driver, host, and database name must be verified; stop if isolation cannot be proven. Tests must not execute DROP, TRUNCATE, ALTER, or other destructive operations on real or shared business databases, nor locally override connections in test files. The author notes that rule text was reviewed but the test base class runtime compliance was not verified.

Case 4: RTK compresses only read‑only output

RTK aims to reduce context noise from command output. Old DEVELOPMENT.md examples placed rtk before git add ., git commit, git push, creating the impression that RTK executes write commands and conflicting with the project's ban on git add .. New examples restrict RTK to read‑only queries:

rtk git status --short
rtk git log -5 --oneline

RTK does not alter write‑command authorization requirements. Staging, commit, and push still follow target‑repo, specific‑file, full‑diff, and staging‑area verification rules. Full patch before commit uses native git diff --no-color and git diff --cached. Short output aids reading but must not become write permission.

Six additional checks from the official guide

Skill descriptions short, trigger conditions precise. Overlong or numerous skills may be truncated; overly broad or conflicting triggers introduce irrelevant instructions.

Expand references on demand. Multi‑process skill entry points can keep only navigation; modifying a skill need not require reading the entire document set; referenced materials must be kept up to date.

Process granularity must suit the user. Overly fine steps may constrain the model; repo rules will be used by other models, so cannot optimize for only one model.

Test reminders can also be excessive. The original post notes Astra actively checks; repeated prompting may cause redundant tests.

Safe workflows need explicit authorization. Example: local tests with no production access and using ephemeral data may run, fix, and re‑test without step‑by‑step confirmation.

Completion criteria must be explicit. Astra may stop after an initial implementation waiting for feedback; tasks should state what still needs verification and where exploration ends.

The author provides a concrete task example for "order amount display correction":

Goal: Correct order amount display, keep settlement and payment behavior unchanged.
Read: First locate display entry and amount conversion logic; read domain notes only when amount definitions are involved.
Verify: First prove test environment isolation, then run minimum necessary affected tests.
Continue condition: If this change causes target tests to fail, fix and re‑test.
Completion condition: Display matches expectation, target tests pass, submit reviewable diff and result explanation.
Stop condition: If settlement definition change, real service access, or expanded authorization is needed, explain why.

The example bundles business goal, verification actions, and stop conditions. Readers should adapt to their own context but not copy the authorization verbatim: test isolation must be proven by environment and connection verification; which operations are autonomous depends on actual task scope.

For team‑shared rules, the author suggests trial runs on a few fixed task types: a copy change, a behavior fix, a change touching shared logic. Record whether unrelated docs are misread, tests are over‑expanded, the agent stops too early, and delivery is complete. This validates whether the new rules work for the models the team actually uses.

What rules should retain

The author now treats AGENTS.md as a task entry point and safety contract, not an encyclopedia. It should declare default target, conditions for reading other documents, rule priority, which actions produce external side effects, and what evidence delivery must provide. Domain details, process examples, and formal specs belong in their respective documents, linked by clear trigger conditions. On‑demand routing and further splitting of long documents remain future work; do not package unsupported ideas as done. A good completion standard: target repo verifiable, config operation triggers explicit, tests never touch real DB, query compression does not bypass write authorization, report explains what was done and what was not.

The most common mistake when writing rules is turning "I worry the agent might err" into "every step must ask me first." A more reliable approach: spell out risky actions, isolation conditions, and acceptance evidence, then leave judgment within the safe boundary to the agent.

Review basis

Project specs: AGENTS.md, DEVELOPMENT.md Change verification: Git diff before/after revision (commit IDs hidden)

Limitations: only document and read‑only Git diff review; no test execution, database, migration, deployment, or measurement of agent token usage, latency, confirmation rounds, or actual behavioral effectiveness.

Official source

OpenAI, September 11, 2026: Rethinking skills and prompts for GPT-6 Astra

https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra