Refactor Agents Md

Refactor AGENTS.md

Refactor an AGENTS.md for GPT-6 Astra. Every retained line enters each Codex session in its scope, so it must earn that attention. Move narrower guidance to the closest applicable scope or a reusable skill, and remove instructions that do not change behavior. Preserve the user's intended behavior and existing authorization.

Instructions

Use request_user_input in Codex when available.

1. Pick the target. Use the target named by the invocation or established in the conversation. If the target remains ambiguous, ask the user to choose among the files that exist:

   • The user-level file at $CODEX_HOME/AGENTS.md, defaulting to ~/.codex/AGENTS.md when CODEX_HOME is unset.
   • The current project's root AGENTS.md.
   • Any nested AGENTS.md on the path from the project root to the current working directory.

2. Consult relevant guidance. Reuse current guidance already fetched in the conversation; fetch missing sections needed for the audit. Preserve explicit user choices where the guides offer defaults. If a source is unavailable, disclose the gap and continue with available evidence.

   • For refactoring criteria: https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra
   • For GPT-6 Astra behavior: https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra#prompting-best-practices
   • When moving guidance between files or resolving loading and precedence: https://learn.chatgpt.com/docs/agent-configuration/agents-md

3. Audit. Match the audit to the request. Read the target and applicable broader AGENTS.md files, then follow references needed to assess scope, conflicts, or claimed redundancy. Treat referenced workflows as audit material. For a full audit or refactor, cover every instruction; for a targeted edit, cover the affected instructions and their interactions. Check repository evidence before declaring a rule stale or derivable. Finish when every instruction in scope has exactly one verdict against the target's bar and GPT-6 checks below.

   • contradiction: conflicts with another applicable instruction. Record both instructions and their source files; resolve conflicts from instruction priority and explicit user intent where possible.
   • delete: fails the no-op test because the models that use the target file would behave the same without it. This includes redundant defaults, vague directions, and platitudes such as "write clean code." Cite the evidence or rationale; retain an explicit constraint when its redundancy is uncertain.
   • demote: changes behavior but applies only to a narrower directory or task. Choose and name its destination. Put directory-specific guidance in the closest nested AGENTS.md; put a multi-step task workflow in a skill; put reference material in a linked document.
   • rewrite: has the right scope and meaning, but its phrasing falls short of the fetched prompting guidance. Also a rewrite when the line carries words that fail the no-op test on their own: a duplicate of another line, a definition of a term the model knows, or emphasis; a rationale or example stays, since both steer the model.
   • keep: earns its always-loaded cost as written.

   Apply the bar for the target:

   • User-level: a keep must express a preference or constraint across projects. Conditional tool and environment rules qualify when their trigger can recur across projects. Demote project or directory guidance to the applicable project's AGENTS.md, and detailed task workflows to skills with reliable triggers.
   • Project or nested: a keep must govern the target directory's subtree; conditional rules belong here when their trigger can occur throughout that scope. Keep concise project context, commands Codex would otherwise guess wrong, domain concepts, constraints, and gotchas that are not obvious from the repository. Delete restatements of the code and volatile inventories such as file trees. Demote narrower guidance to a closer nested AGENTS.md, a linked document, or a skill.

4. Resolve decisions. For an assessment, report findings without editing. For an authorized refactor or edit, carry the requested changes through verification using decisions already established in the conversation. Preserve explicit review boundaries; ask only about unresolved contradictions or behavior changes outside the authorized scope. Prepare the proposed rewrite and affected delete or demote lists, including destinations, before asking. Use request_user_input when available and permitted; otherwise ask one concise question. Continue independent work while decisions are pending.

5. Rewrite and verify. Apply only authorized changes. Search references before removing or moving guidance, and update affected pointers. Place each new nested AGENTS.md in the nearest directory whose whole subtree shares its guidance. Check the final diff for preserved intent, resolved conflicts, and reachable destinations. Finish when every audited instruction is accounted for and required checks pass; report changed files and any unresolved decisions concisely.