{"id":495428,"date":"2026-09-21T11:52:17","date_gmt":"2026-09-21T11:52:17","guid":{"rendered":"https:\/\/savepearlharbor.com\/?p=495428"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=495428","title":{"rendered":"How to Review AGENTS.md for GPT-6 Astra in Codex"},"content":{"rendered":"<div xmlns=\"http:\/\/www.w3.org\/1999\/xhtml\">\n<p>A small code change can lead to a lot of extra work when a project has broad instructions. You ask Codex to fix a button label, but <code>AGENTS.md<\/code> tells it to read the database guide, study the deployment process, and run every check three times.<\/p>\n<p>Those steps may follow the file exactly. They may also have little to do with the requested change.<\/p>\n<p>OpenAI\u2019s <a href=\"https:\/\/developers.openai.com\/blog\/rethinking-skills-and-prompts-for-gpt-6-astra\" rel=\"noopener nofollow\">guide to skills and prompts for GPT-6 Astra<\/a> suggests reviewing instructions written for earlier models. In this article, I will focus on one part of that work: finding rules in <code>AGENTS.md<\/code> that are unclear, too broad, or no longer useful.<\/p>\n<p>The examples below describe a sample project. They are a way to review your own rules, not measured results from a performance test.<\/p>\n<h3>What belongs in AGENTS.md<\/h3>\n<p><code>AGENTS.md<\/code> gives Codex standing instructions for a project. It is a useful place for facts that matter across many tasks:<\/p>\n<ul>\n<li>\n<p>Where source files live.<\/p>\n<\/li>\n<li>\n<p>Which files are generated.<\/p>\n<\/li>\n<li>\n<p>Which commands check the project.<\/p>\n<\/li>\n<li>\n<p>Which documents explain important parts of the system.<\/p>\n<\/li>\n<li>\n<p>Which actions need approval.<\/p>\n<\/li>\n<\/ul>\n<p>A filename for today\u2019s report or the wording of a new button usually belongs in the current task prompt.<\/p>\n<p>Skills serve another purpose. A <code>SKILL.md<\/code> file describes a reusable job, such as preparing an invoice or reviewing a migration. The task prompt, project instructions, and selected skills can all affect the same run. A review should consider how they fit together.<\/p>\n<h3>Start with the instructions Codex actually reads<\/h3>\n<p>Before editing a rule, check its source.<\/p>\n<p>OpenAI\u2019s <a href=\"https:\/\/learn.chatgpt.com\/docs\/agent-configuration\/agents-md\" rel=\"noopener nofollow\">AGENTS.md documentation<\/a> explains how Codex combines global and project instructions. It looks for guidance along the path from the project root to the current working directory. More local guidance can override earlier guidance. An <code>AGENTS.override.md<\/code> file can take priority over <code>AGENTS.md<\/code> in the same directory.<\/p>\n<p>This means the file at the repository root may not be the only source of a repeated pause or an extra check.<\/p>\n<p>Ask Codex:<\/p>\n<pre><code>List the instruction files that apply to this task.For each file, give its path and the rules that affectreading documents, running checks, and asking for approval.Report conflicts or missing files. Do not change anything yet.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:87px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>In the CLI, start a fresh session after changing project instructions. Then check which sources were loaded. This helps avoid testing an edit against an older set of instructions.<\/p>\n<h3>Find rules that apply too widely<\/h3>\n<p>Suppose a project has this rule:<\/p>\n<pre><code class=\"markdown\">Before every edit, read:- docs\/ui.md- docs\/database.md- docs\/deployment.md- docs\/architecture.md<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>The documents may all be useful. The phrase \u201cbefore every edit\u201d is the part to examine.<\/p>\n<p>A database change needs the database guide. A deployment needs the deployment guide. A spelling correction may need neither.<\/p>\n<p>A more focused version is:<\/p>\n<pre><code class=\"markdown\">## Project documents- Read docs\/ui.md for interface changes.- Read docs\/database.md for schema or data-storage changes.- Read docs\/deployment.md when preparing a deployment.- Read docs\/architecture.md when changing service boundaries.Read every guide that applies when a task crosses these areas.Keep the relevant documents current when behavior changes.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Use paths that exist in your project. If a document contains rules that apply to every task, keep that requirement. You could also move its short, general rules into <code>AGENTS.md<\/code> and leave the detailed workflow in the document.<\/p>\n<p>The aim is to make the scope clear. Deleting a required guide because it is long does not solve that problem.<\/p>\n<h3>Separate required checks from repeated checks<\/h3>\n<p>Another rule worth reviewing is:<\/p>\n<pre><code>Run the full test suite three times after every edit.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Repeated runs can help investigate a test that sometimes fails. They can also be part of a release process. But the rule above does not explain why every edit needs three runs.<\/p>\n<p>Start with the checks your project requires. Then describe what should happen when something fails:<\/p>\n<pre><code class=\"markdown\">## VerificationRun the checks required for the affected part of the project.Keep the full release checks when preparing a release.Fix failures caused by the requested change and rerun theaffected checks. Report unrelated failures separately.Repeat or broaden checks when a new change, a failure, or anunresolved concern gives you a reason to do so.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>If the team requires a full build for a source change, keep it. Removing duplicate work should not remove an agreed requirement.<\/p>\n<p>Also name the evidence you need. A successful build shows that the app can build. It does not prove that clearing a search field restores the full list. That behavior needs its own check.<\/p>\n<h3>Explain what the agent may finish on its own<\/h3>\n<p>\u201cAsk before making changes\u201d can mean several things. Does it cover a local source edit, a test run, a database update, or a production deployment?<\/p>\n<p>Name the actions:<\/p>\n<pre><code>You may edit files in this project and fix problems causedby the requested change.Run local checks that use the project's confirmed disposabletest data. Ask before changing production data or deploying.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Only describe test data as disposable after checking that this is true. A command run on your laptop may still connect to a shared service.<\/p>\n<p>These instructions explain your intent. They do not change Codex\u2019s technical permissions. The <a href=\"https:\/\/learn.chatgpt.com\/docs\/sandboxing\" rel=\"noopener nofollow\">sandbox<\/a> still controls which files and network resources commands can access.<\/p>\n<h3>Give the task a clear stopping point<\/h3>\n<p>An instruction file can also cause Codex to stop earlier than you expect. For example, \u201creturn the first version for review\u201d may conflict with a request to implement and check the whole change.<\/p>\n<p>For a small bug fix, a task prompt could say:<\/p>\n<pre><code>Fix the search filter so clearing the input restores all items.Keep the current layout.Complete the edit and the required project checks. Verifysearching, no results, and clearing the input in a local previewif browser access is available.Fix problems caused by this change. Finish with the result,the checks performed, and any verification you could not complete.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>If you do want a plan or a draft before implementation, say so. The stopping point should match the decision you need to make.<\/p>\n<h3>Ask for proposed edits, not a shorter file<\/h3>\n<p>An instruction review needs a clear purpose. \u201cMake this file shorter\u201d may remove a rule that protects a real requirement.<\/p>\n<p>Try this prompt:<\/p>\n<pre><code>Review the applicable AGENTS.md files using this guide:https:\/\/developers.openai.com\/blog\/rethinking-skills-and-prompts-for-gpt-6-astraLook for broad reading rules, unclear approval boundaries,repeated checks, stale paths, and conflicting stopping rules.For each useful change, show:- The file and current wording.- A task where the wording could cause a problem.- A proposed replacement.- The requirement that the replacement keeps.- A task we can use to check the new rule.Keep required checks and approval boundaries.Flag unclear requirements for review. Do not edit files yet.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>The result should help you make a small decision. \u201cRead the deployment guide only for deployment work\u201d is specific enough to review. \u201cThere is too much context\u201d needs more explanation.<\/p>\n<h3>Check the change with familiar tasks<\/h3>\n<p>Save the old file, approve one edit, and try tasks whose expected results you understand.<\/p>\n<p>For example, use a text correction, a small interface fix, and a data-storage change. Check whether Codex reads the right documents and still runs the required checks for each one.<\/p>\n<p>Keep the model and task inputs the same when comparing versions. Review the output and the visible work, including file reads, checks, and approval requests. One successful run gives limited evidence, so try more than one kind of task before changing shared guidance.<\/p>\n<p>If teammates use other models, include those models in the review. OpenAI notes that instructions useful for Sol or Luna may constrain Astra differently.<\/p>\n<p>Start with a rule that has caused a clear problem. Keep the edit if it improves that task while preserving the project\u2019s requirements.<\/p>\n<h3>Video and sources<\/h3>\n<div class=\"tm-iframe_temp\" data-src=\"https:\/\/embedd.srv.habr.com\/iframe\/6ab11a714903ae0dbe7f7199\" data-style=\"\" id=\"6ab11a714903ae0dbe7f7199\" width=\"\" data-habr-games=\"\"><\/div>\n<p>I cover this topic alongside prompts and skills in my <a href=\"https:\/\/youtu.be\/FESNAh3gNyQ\" rel=\"noopener nofollow\">seven-tip video tutorial<\/a>. The <a href=\"https:\/\/proflead.dev\/posts\/gpt-6-astra-codex-prompts-skills-agents-md\/\" rel=\"noopener nofollow\">full guide on my website<\/a> includes more examples and an instruction-audit prompt.<\/p>\n<ul>\n<li>\n<p><a href=\"https:\/\/developers.openai.com\/blog\/rethinking-skills-and-prompts-for-gpt-6-astra\" rel=\"noopener nofollow\">OpenAI: Rethinking skills and prompts for GPT-6 Astra<\/a>, September 11, 2026.<\/p>\n<\/li>\n<li>\n<p><a href=\"https:\/\/learn.chatgpt.com\/docs\/agent-configuration\/agents-md\" rel=\"noopener nofollow\">OpenAI: Custom instructions with AGENTS.md<\/a>.<\/p>\n<\/li>\n<li>\n<p><a href=\"https:\/\/learn.chatgpt.com\/docs\/build-skills\" rel=\"noopener nofollow\">OpenAI: Skills<\/a>.<\/p>\n<\/li>\n<li>\n<p><a href=\"https:\/\/learn.chatgpt.com\/docs\/sandboxing\" rel=\"noopener nofollow\">OpenAI: Sandbox<\/a>.<\/p>\n<\/li>\n<\/ul>\n<\/div>\n<p>\u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438 <a href=\"https:\/\/habr.com\/ru\/articles\/1084676\/\">https:\/\/habr.com\/ru\/articles\/1084676\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>A small code change can lead to a lot of extra work when a project has broad instructions. You ask Codex to fix a button label, but AGENTS.md tells it to read the database guide, study the deployment process, and run every check three times.Those steps may follow the file exactly. They may also have little to do with the requested change.OpenAI\u2019s guide to skills and prompts for GPT-6 Astra suggests reviewing instructions written for earlier models. In this article, I will focus on one part of that work: finding rules in AGENTS.md that are unclear, too broad, or no longer useful.The examples below describe a sample project. They are a way to review your own rules, not measured results from a performance test.What belongs in AGENTS.mdAGENTS.md gives Codex standing instructions for a project. It is a useful place for facts that matter across many tasks:Where source files live.Which files are generated.Which commands check the project.Which documents explain important parts of the system.Which actions need approval.A filename for today\u2019s report or the wording of a new button usually belongs in the current task prompt.Skills serve another purpose. A SKILL.md file describes a reusable job, such as preparing an invoice or reviewing a migration. The task prompt, project instructions, and selected skills can all affect the same run. A review should consider how they fit together.Start with the instructions Codex actually readsBefore editing a rule, check its source.OpenAI\u2019s AGENTS.md documentation explains how Codex combines global and project instructions. It looks for guidance along the path from the project root to the current working directory. More local guidance can override earlier guidance. An AGENTS.override.md file can take priority over AGENTS.md in the same directory.This means the file at the repository root may not be the only source of a repeated pause or an extra check.Ask Codex:List the instruction files that apply to this task.For each file, give its path and the rules that affectreading documents, running checks, and asking for approval.Report conflicts or missing files. Do not change anything yet.In the CLI, start a fresh session after changing project instructions. Then check which sources were loaded. This helps avoid testing an edit against an older set of instructions.Find rules that apply too widelySuppose a project has this rule:Before every edit, read:- docs\/ui.md- docs\/database.md- docs\/deployment.md- docs\/architecture.mdThe documents may all be useful. The phrase \u201cbefore every edit\u201d is the part to examine.A database change needs the database guide. A deployment needs the deployment guide. A spelling correction may need neither.A more focused version is:## Project documents- Read docs\/ui.md for interface changes.- Read docs\/database.md for schema or data-storage changes.- Read docs\/deployment.md when preparing a deployment.- Read docs\/architecture.md when changing service boundaries.Read every guide that applies when a task crosses these areas.Keep the relevant documents current when behavior changes.Use paths that exist in your project. If a document contains rules that apply to every task, keep that requirement. You could also move its short, general rules into AGENTS.md and leave the detailed workflow in the document.The aim is to make the scope clear. Deleting a required guide because it is long does not solve that problem.Separate required checks from repeated checksAnother rule worth reviewing is:Run the full test suite three times after every edit.Repeated runs can help investigate a test that sometimes fails. They can also be part of a release process. But the rule above does not explain why every edit needs three runs.Start with the checks your project requires. Then describe what should happen when something fails:## VerificationRun the checks required for the affected part of the project.Keep the full release checks when preparing a release.Fix failures caused by the requested change and rerun theaffected checks. Report unrelated failures separately.Repeat or broaden checks when a new change, a failure, or anunresolved concern gives you a reason to do so.If the team requires a full build for a source change, keep it. Removing duplicate work should not remove an agreed requirement.Also name the evidence you need. A successful build shows that the app can build. It does not prove that clearing a search field restores the full list. That behavior needs its own check.Explain what the agent may finish on its own\u201cAsk before making changes\u201d can mean several things. Does it cover a local source edit, a test run, a database update, or a production deployment?Name the actions:You may edit files in this project and fix problems causedby the requested change.Run local checks that use the project&#8217;s confirmed disposabletest data. Ask before changing production data or deploying.Only describe test data as disposable after checking that this is true. A command run on your laptop may still connect to a shared service.These instructions explain your intent. They do not change Codex\u2019s technical permissions. The sandbox still controls which files and network resources commands can access.Give the task a clear stopping pointAn instruction file can also cause Codex to stop earlier than you expect. For example, \u201creturn the first version for review\u201d may conflict with a request to implement and check the whole change.For a small bug fix, a task prompt could say:Fix the search filter so clearing the input restores all items.Keep the current layout.Complete the edit and the required project checks. Verifysearching, no results, and clearing the input in a local previewif browser access is available.Fix problems caused by this change. Finish with the result,the checks performed, and any verification you could not complete.If you do want a plan or a draft before implementation, say so. The stopping point should match the decision you need to make.Ask for proposed edits, not a shorter fileAn instruction review needs a clear purpose. \u201cMake this file shorter\u201d may remove a rule that protects a real requirement.Try this prompt:Review the applicable AGENTS.md files using this guide:https:\/\/developers.openai.com\/blog\/rethinking-skills-and-prompts-for-gpt-6-astraLook for broad reading rules, unclear approval boundaries,repeated checks, stale paths, and conflicting stopping rules.For each useful change, show:- The file and current wording.- A task where the wording could cause a problem.- A proposed replacement.- The requirement that the replacement keeps.- A task we can use to check the new rule.Keep required checks and approval boundaries.Flag unclear requirements for review. Do not edit files yet.The result should help you make a small decision. \u201cRead the deployment guide only for deployment work\u201d is specific enough to review. \u201cThere is too much context\u201d needs more explanation.Check the change with familiar tasksSave the old file, approve one edit, and try tasks whose expected results you understand.For example, use a text correction, a small interface fix, and a data-storage change. Check whether Codex reads the right documents and still runs the required checks for each one.Keep the model and task inputs the same when comparing versions. Review the output and the visible work, including file reads, checks, and approval requests. One successful run gives limited evidence, so try more than one kind of task before changing shared guidance.If teammates use other models, include those models in the review. OpenAI notes that instructions useful for Sol or Luna may constrain Astra differently.Start with a rule that has caused a clear problem. Keep the edit if it improves that task while preserving the project\u2019s requirements.Video and sourcesI cover this topic alongside prompts and skills in my seven-tip video tutorial. The full guide on my website includes more examples and an instruction-audit prompt.OpenAI: Rethinking skills and prompts for GPT-6 Astra, September 11, 2026.OpenAI: Custom instructions with AGENTS.md.OpenAI: Skills.OpenAI: Sandbox.\u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438 https:\/\/habr.com\/ru\/articles\/1084676\/<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-495428","post","type-post","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/495428","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=495428"}],"version-history":[{"count":0,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/495428\/revisions"}],"wp:attachment":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=495428"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=495428"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=495428"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}