#Practical Examples

Three end-to-end scenarios from simple to advanced, showing how AGENTS.md, sandbox, Skills, and MCP combine.

#Example 1: Legacy module refactor

Background: legacy/billing.js is a 2000-line file with no tests.

#Steps

1. Branch and AGENTS.md

git checkout -b refactor/billing-module

In legacy/AGENTS.md:

# legacy/AGENTS.md
- Keep public export names unchanged during refactor
- Each extracted module must have matching unit tests
- Test command: `npm test -- legacy/billing`

2. Read-only exploration (optional subagent or first pass)

codex --sandbox read-only --ask-for-approval on-request

Analyze legacy/billing.js responsibilities and propose splitting into payment, invoice, and tax modules with a file tree. Do not modify files.

3. Implement refactor

codex --sandbox workspace-write --ask-for-approval on-request

Split legacy/billing.js per the plan above, add tests, and run npm test -- legacy/billing until green.

4. Review

git diff --stat
npm test
# Or use Codex local code review

Takeaway: Separate explore and implement phases + directory-scoped AGENTS.md.

#Example 2: Automated pre-commit review Skill

Goal: Run a fixed checklist on staged diff before every PR.

#Create Skill .agents/skills/pre-commit-review/SKILL.md

---
name: pre-commit-review
description: Review git staged diff. Use when the user mentions review, pre-commit check, or PR self-review.
---

1. Run `git diff --cached` for changes.
2. Check for: debug statements, secrets, oversized files, missing tests.
3. Output by severity: BLOCKER / WARN / INFO.
4. Do not modify files; report only.

#Usage

git add -p
codex

$pre-commit-review

Extension: Add GitHub MCP steps to compare against the base branch diff.

#Example 3: Issue → branch → PR (Cloud + local)

Background: GitHub Issues track work; Codex Cloud implements async; local is for acceptance.

#Cloud

1. Connect the repo at chatgpt.com/codex
2. Match environment (Node version, test command) to AGENTS.md
3. Start task: “Fix #42: login timeout does not refresh token”

#Local

git fetch
git checkout codex/issue-42-fix
npm test
codex --sandbox read-only "Check acceptance criteria for Issue #42 as a checklist"

#PR comment

On the PR: @codex add regression test for token refresh for follow-up iteration.

Takeaway: Same AGENTS.md on Cloud and CLI avoids environment drift.

#Example 4: Release notes in CI

# .github/workflows/release-notes.yml (illustrative)
- name: Codex release notes
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    codex exec \
      --sandbox read-only \
      --ask-for-approval never \
      --output-last-message \
      "From git log $(git describe --tags --abbrev=0)..HEAD write user-facing changelog in Markdown" \
      > RELEASE_NOTES.md

Takeaway: CI uses read-only + no approvals; checkout should be write-restricted.

#Anti-patterns (avoid)

#Next steps

• Resources: official docs and community
• Agent Skills: package Example 2 as a Plugin