From ae88b69b09f876a3017196a9cd66f83dac79d9d7 Mon Sep 17 00:00:00 2001 From: Michael Bolin Date: Wed, 6 Aug 2025 10:39:58 -0700 Subject: [PATCH 1/2] fix: add more instructions to ensure GitHub Action reviews only the necessary code (#1887) Empirically, we have seen the GitHub Action comment on code outside of the PR, so try to provide additional instructions in the prompt to avoid this. --- .github/actions/codex/src/process-label.ts | 33 +++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/.github/actions/codex/src/process-label.ts b/.github/actions/codex/src/process-label.ts index 4b4361e118..60207efaaa 100644 --- a/.github/actions/codex/src/process-label.ts +++ b/.github/actions/codex/src/process-label.ts @@ -91,7 +91,38 @@ async function processLabel( labelConfig: LabelConfig, ): Promise { const template = labelConfig.getPromptTemplate(); - const populatedTemplate = await renderPromptTemplate(template, ctx); + + // If this is a review label, prepend explicit PR-diff scoping guidance to + // reduce out-of-scope feedback. Do this before rendering so placeholders in + // the guidance (e.g., {CODEX_ACTION_GITHUB_EVENT_PATH}) are substituted. + const isReview = label.toLowerCase().includes("review"); + const reviewScopeGuidance = ` +PR Diff Scope +- Only review changes between the PR's merge-base and head; do not comment on commits or files outside this range. +- Derive the base/head SHAs from the event JSON at {CODEX_ACTION_GITHUB_EVENT_PATH}, then compute and use the PR diff for all analysis and comments. + +Commands to determine scope +- Resolve SHAs: + - BASE_SHA=$(jq -r '.pull_request.base.sha // .pull_request.base.ref' "{CODEX_ACTION_GITHUB_EVENT_PATH}") + - HEAD_SHA=$(jq -r '.pull_request.head.sha // .pull_request.head.ref' "{CODEX_ACTION_GITHUB_EVENT_PATH}") + - BASE_SHA=$(git rev-parse "$BASE_SHA") + - HEAD_SHA=$(git rev-parse "$HEAD_SHA") +- Prefer triple-dot (merge-base) semantics for PR diffs: + - Changed commits: git log --oneline "$BASE_SHA...$HEAD_SHA" + - Changed files: git diff --name-status "$BASE_SHA...$HEAD_SHA" + - Review hunks: git diff -U0 "$BASE_SHA...$HEAD_SHA" + +Review rules +- Anchor every comment to a file and hunk present in git diff "$BASE_SHA...$HEAD_SHA". +- If you mention context outside the diff, label it as "Follow-up (outside this PR scope)" and keep it brief (<=2 bullets). +- Do not critique commits or files not reachable in the PR range (merge-base(base, head) → head). +`.trim(); + + const effectiveTemplate = isReview + ? `${reviewScopeGuidance}\n\n${template}` + : template; + + const populatedTemplate = await renderPromptTemplate(effectiveTemplate, ctx); // Always run Codex and post the resulting message as a comment. let commentBody = await runCodex(populatedTemplate, ctx); From ba025cbbb0793dd42d87cd9c6df255f7a6d5b6ff Mon Sep 17 00:00:00 2001 From: Michael Bolin Date: Wed, 6 Aug 2025 11:11:31 -0700 Subject: [PATCH 2/2] fix: support $CODEX_HOME/AGENTS.md instead of $CODEX_HOME/instructions.md --- codex-cli/examples/prompting_guide.md | 10 +++++----- codex-rs/core/src/config.rs | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/codex-cli/examples/prompting_guide.md b/codex-cli/examples/prompting_guide.md index cadeb1a9bb..4e434d9db6 100644 --- a/codex-cli/examples/prompting_guide.md +++ b/codex-cli/examples/prompting_guide.md @@ -45,14 +45,14 @@ Enter "q" to exit out of the current session and `open poem.html`. You should se ## Custom instructions -Codex supports two types of Markdown-based instruction files that influence model behavior and prompting: +Codex supports Markdown-based instruction files that influence model behavior and prompting: -### `~/.codex/instructions.md` -Global, user-level custom guidance injected into every session. You should keep this relatively short and concise. These instructions are applied to all Codex runs across all projects and are great for personal defaults, shell setup tips, safety constraints, or preferred tools. +### `~/.codex/AGENTS.md` +Global, user-level custom guidance injected into every session. Keep this relatively short and concise. These instructions are applied to all Codex runs across all projects and are great for personal defaults, shell setup tips, safety constraints, or preferred tools. **Example:** "Before executing shell commands, create and activate a `.codex-venv` Python environment." or "Avoid running pytest until you've completed all your changes." -### `CODEX.md` +### `AGENTS.md` Project-specific instructions loaded from the current directory or Git root. Use this for repo-specific context, file structure, command policies, or project conventions. These are automatically detected unless `--no-project-doc` or `CODEX_DISABLE_PROJECT_DOC=1` is set. **Example:** “All React components live in `src/components/`". @@ -80,7 +80,7 @@ For more complex tasks requiring longer form input, you can write the instructio `codex "$(cat task_description.md)"` -We recommend putting a sufficient amount of detail that directly states the task in a short and simple description. Add any relevant context that you’d share with someone new to your codebase (if not already in `CODEX.md`). You can also include any files Codex should read for more context, edit or take inspiration from, along with any preferences for how Codex should verify its work. +We recommend putting a sufficient amount of detail that directly states the task in a short and simple description. Add any relevant context that you’d share with someone new to your codebase (if not already in `AGENTS.md`). You can also include any files Codex should read for more context, edit or take inspiration from, along with any preferences for how Codex should verify its work. If Codex doesn’t get it right on the first try, give feedback to fix when you're in interactive mode! diff --git a/codex-rs/core/src/config.rs b/codex-rs/core/src/config.rs index 0b53df5ab7..f48cc9340b 100644 --- a/codex-rs/core/src/config.rs +++ b/codex-rs/core/src/config.rs @@ -70,7 +70,7 @@ pub struct Config { /// who have opted into Zero Data Retention (ZDR). pub disable_response_storage: bool, - /// User-provided instructions from instructions.md. + /// User-provided instructions from AGENTS.md. pub user_instructions: Option, /// Base instructions override. @@ -575,7 +575,7 @@ impl Config { None => return None, }; - p.push("instructions.md"); + p.push("AGENTS.md"); std::fs::read_to_string(&p).ok().and_then(|s| { let s = s.trim(); if s.is_empty() {