Codex 实战指南

# AGENTS.md
 
## Project Overview
 
This is a React + TypeScript dashboard project.
 
## Tech Stack
 
- React
- TypeScript
- Vite
- Tailwind CSS
- Vitest
 
## Common Commands
 
- Install dependencies: `npm install`
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Run build: `npm run build`
- Run lint: `npm run lint`
 
## Project Structure
 
- `src/components/`: shared UI components
- `src/pages/`: route-level pages
- `src/hooks/`: reusable React hooks
- `src/services/`: API and business logic
- `src/tests/`: test utilities and integration tests
 
## Coding Rules
 
- Use TypeScript for all new code.
- Follow the existing file and folder structure.
- Prefer existing components from `src/components/ui`.
- Do not introduce new dependencies unless necessary.
- Keep diffs small and focused.
 
## Testing Rules
 
- Add tests for bug fixes.
- Update tests when behavior changes.
- Run the most relevant test command before final response.
 
## Restrictions
 
- Do not modify generated files.
- Do not change public APIs unless explicitly requested.
- Do not format unrelated files.

# AGENTS.md
 
## How Codex Should Work In This Repository
 
Before editing code:
 
1. Read the relevant files.
2. Explain the likely change plan.
3. Prefer the smallest safe change.
4. Ask before changing public APIs or adding dependencies.
 
After editing code:
 
1. Show a summary of changed files.
2. Explain why each change was made.
3. Run relevant tests when possible.
4. Mention any tests that were not run.
 
## Code Review Standards
 
When reviewing code, check for:
 
- logic bugs
- unhandled edge cases
- missing tests
- security risks
- backward compatibility issues
- unnecessary dependencies
 
Use severity labels:
 
- P0: must fix before merge
- P1: should fix soon
- P2: optional improvement
 
## Do Not
 
- Do not rewrite large modules without approval.
- Do not rename files unless necessary.
- Do not change formatting-only diffs in unrelated files.
- Do not paste or expose secrets.

skills/
└── pr-review/
    ├── SKILL.md
    ├── references/
    │   └── review-standards.md
    ├── scripts/
    │   └── collect-diff.sh
    └── assets/
        └── pr-template.md

---
name: pr-review
description: Review pull requests and git diffs for correctness, safety, and maintainability.
---
 
# PR Review Skill
 
## When to use
 
Use this skill when the user asks for:
 
- PR review
- code review
- diff review
- regression check
- merge readiness check
 
## Workflow
 
1. Inspect the current git diff.
2. Identify the changed behavior.
3. Check for bugs, missing tests, security issues, and breaking changes.
4. Do not edit files unless explicitly asked.
5. Group findings by severity.
6. If no major issues are found, say so clearly.
 
## Severity
 
- P0: Must fix before merge.
- P1: Should fix soon.
- P2: Optional improvement.
 
## Output Format
 
For each finding, include:
 
- Severity
- File or area
- Problem
- Why it matters
- Suggested fix
 
## Constraints
 
- Do not nitpick style unless it affects maintainability.
- Do not request unrelated refactors.
- Do not invent issues without evidence from the diff.

---
name: bug-investigation
description: Investigate bugs by reproducing, locating root cause, applying minimal fixes, and verifying results.
---
 
# Bug Investigation Skill
 
## When to use
 
Use this skill when the user provides:
 
- an error message
- failing test output
- broken behavior
- production bug report
- regression description
 
## Workflow
 
1. Read the bug report and identify the expected behavior.
2. Locate relevant files and tests.
3. Try to reproduce the bug.
4. Explain the likely root cause before editing.
5. Make the smallest safe fix.
6. Run the most relevant test.
7. Summarize changed files and validation steps.
 
## Rules
 
- Prefer minimal fixes over broad refactors.
- Do not hide failing tests.
- Do not change public behavior unless required by the bug.
- If the bug cannot be reproduced, explain what was checked.
 
## Final Response
 
Include:
 
- root cause
- files changed
- fix summary
- tests run
- remaining risks

---
name: docs-writer
description: Write clear project documentation with overview, setup, usage, examples, and FAQ.
---
 
# Docs Writer Skill
 
## When to use
 
Use this skill when writing or updating:
 
- README
- API docs
- setup guide
- user guide
- internal engineering docs
 
## Workflow
 
1. Read the relevant code or existing documentation.
2. Identify the audience.
3. Explain the purpose first.
4. Provide practical examples.
5. Add troubleshooting notes where useful.
6. Keep language direct and scannable.
 
## Output Structure
 
Use this structure by default:
 
1. Overview
2. Requirements
3. Usage
4. Examples
5. Configuration
6. Troubleshooting
7. FAQ
 
## Style Rules
 
- Prefer concrete examples over abstract descriptions.
- Avoid overclaiming.
- Keep headings short.
- Use code blocks for commands and config.
 

my-codex-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── pr-review/
│   │   └── SKILL.md
│   ├── bug-investigation/
│   │   └── SKILL.md
│   └── docs-writer/
│       └── SKILL.md
├── .mcp.json
├── .app.json
├── hooks/
│   └── hooks.json
└── assets/
    ├── icon.png
    └── screenshot.png

{
  "name": "team-codex-plugin",
  "version": "0.1.0",
  "description": "Reusable Codex workflows for engineering teams.",
  "author": {
    "name": "Your Team",
    "email": "team@example.com"
  },
  "license": "MIT",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "Team Codex Plugin",
    "shortDescription": "Team workflows for PR review, bug fixes, and docs.",
    "longDescription": "A shared Codex plugin that packages team coding standards, review workflows, documentation workflows, and MCP integrations.",
    "developerName": "Your Team",
    "category": "Developer Tools",
    "capabilities": ["Read", "Write"],
    "defaultPrompt": [
      "Review this pull request using our team review standards.",
      "Investigate this bug and propose the smallest safe fix.",
      "Update the documentation for this module."
    ],
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/icon.png"
  }
}

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.internal_docs]
url = "https://mcp.example.com"
bearer_token_env_var = "INTERNAL_DOCS_TOKEN"

team-research-plugin/
├── skills/
│   └── weekly-summary/
│       └── SKILL.md
├── .app.json
└── .codex-plugin/
    └── plugin.json

Use subagents to analyze this repository.

Assign separate subagents to:
1. frontend architecture
2. backend architecture
3. testing strategy
4. security risks

Each subagent should return:
- key files
- architecture summary
- risks
- recommended follow-up tasks

Then combine the results into one final report.
Do not modify files.

Use subagents to investigate the migration from REST API calls to GraphQL.

Assign subagents to:
1. find all REST API call sites
2. analyze data types and response shapes
3. inspect tests and mocks
4. identify migration risks

Return a phased migration plan.
Do not edit code yet.

# rules/default.rules
 
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Viewing PRs is allowed with approval",
    match = [
        "gh pr view 123",
        "gh pr view --repo owner/repo 123"
    ],
    not_match = [
        "gh pr list"
    ]
)

prefix_rule(
    pattern = ["rm", "-rf"],
    decision = "forbidden",
    justification = "Dangerous recursive deletion is blocked. Use a safer file-specific delete command instead."
)

Every weekday morning, check whether this project has outdated dependencies.
If there are safe patch updates, summarize them.
Do not modify files unless explicitly asked.

Every Friday afternoon, summarize this week's repository changes.
Include:
- notable commits
- changed modules
- risky changes
- missing tests
- suggested follow-ups

codex exec "Review the current git diff and report bugs, risks, and missing tests. Do not edit files."

codex exec "Summarize this repository architecture" --output-last-message report.md

codex exec "Review this pull request for regressions and security risks. Do not edit files."

name: Codex PR Review
 
on:
  pull_request:
    types: [opened, synchronize, reopened]
 
jobs:
  codex-review:
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
 
      - name: Run Codex review
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review this pull request.
            Focus on:
            - logic bugs
            - security risks
            - missing tests
            - breaking changes
            Do not modify files.

name: Codex Release Check
 
on:
  workflow_dispatch:
 
jobs:
  release-check:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Perform a release readiness review.
            Check:
            - changelog completeness
            - test coverage risks
            - breaking changes
            - migration notes
            - documentation updates
            Do not edit files.

Use the browser to open http://localhost:3000/settings.
Reproduce the layout bug.
Fix only the overflowing controls.
Keep the existing component structure unchanged.
I left comments on the pricing page in the in-app browser.
Address the mobile layout issues only.
Do not change the desktop layout.

Open the app with computer use.
Reproduce the onboarding bug.
Fix the smallest code path that causes it.
After each change, run the same UI flow again.
Open @Chrome and verify the checkout page still works after the latest changes.
Do not enter real payment information.

codex exec 或 GitHub Action

docs/
├── README.md
├── codex/
│   ├── README.md
│   ├── capability-model.md
│   ├── agents-md.md
│   ├── memories.md
│   ├── skills.md
│   ├── plugins.md
│   ├── mcp.md
│   ├── apps.md
│   ├── subagents.md
│   ├── sandbox.md
│   ├── rules.md
│   ├── hooks.md
│   ├── worktrees.md
│   ├── automations.md
│   ├── codex-exec.md
│   ├── github-action.md
│   ├── sdk.md
│   ├── in-app-browser.md
│   ├── computer-use.md
│   ├── slash-commands.md
│   ├── best-practices.md
│   └── faq.md
└── examples/
    ├── agents-md-basic.md
    ├── pr-review-skill.md
    ├── bug-investigation-skill.md
    ├── docs-writer-skill.md
    ├── team-plugin.md
    ├── mcp-config.md
    ├── rules-examples.md
    └── github-action-review.md

# AGENTS.md
 
## Project Rules
 
- Keep changes small and focused.
- Follow existing code style.
- Do not add dependencies without explaining why.
- Do not modify generated files.
- Run relevant tests after editing.
 
## Commands
 
- Install: `npm install`
- Test: `npm test`
- Build: `npm run build`

---
name: pr-review
description: Review code diffs for bugs, risks, and missing tests.
---
 
# PR Review
 
When reviewing code:
 
1. Inspect the diff.
2. Identify behavior changes.
3. Check for bugs, missing tests, security issues, and breaking changes.
4. Do not edit files unless asked.
5. Group findings by P0, P1, and P2.
 
If there are no major issues, say so clearly.

---
name: bug-investigation
description: Investigate bugs, identify root causes, and apply minimal safe fixes.
---
 
# Bug Investigation
 
1. Reproduce or inspect the failure.
2. Find the likely root cause.
3. Explain the fix before editing.
4. Make the smallest safe change.
5. Run relevant tests.
6. Summarize what changed and what was verified.