---
name: revise-claude-md
description: Capture useful learnings from the current session into AGENTS.md, CLAUDE.md, .agents.local.md, or .claude.local.md. Use when the user asks to revise project instructions, update project memory, capture session learnings, or run the Claude /revise-claude-md workflow in Codex.
---

# Revise Project Instructions

Review the current session for durable learnings about working in this codebase, then propose concise updates to the appropriate project instruction file.

## Step 1: Reflect

Identify context that would help future Codex or Claude sessions:

- Commands that were used or discovered
- Code style patterns that were followed
- Testing approaches that worked
- Environment or configuration quirks
- Recurring warnings, gotchas, or workflow constraints

Only keep information likely to recur. Do not capture one-off debugging details or generic software engineering advice.

## Step 2: Find Instruction Files

Search for relevant files:

```powershell
rg --files | rg '(^|/)(AGENTS\.md|CLAUDE\.md|\.agents\.local\.md|\.claude\.local\.md)$'
```

Choose the target file:

- `AGENTS.md`: Codex project instructions shared with the team
- `CLAUDE.md`: Claude Code project context shared with the team
- `.agents.local.md`: personal/local Codex notes, normally gitignored
- `.claude.local.md`: personal/local Claude notes, normally gitignored

When the repo has `AGENTS.md`, prefer it for Codex-specific rules. When the repo has only `CLAUDE.md`, use `CLAUDE.md` unless the user asks to create an `AGENTS.md`.

## Step 3: Draft Additions

Keep additions concise. One line per concept is usually enough.

Format:

```text
<command or pattern> - <brief description>
```

Avoid:

- Verbose explanations
- Obvious information
- One-off fixes unlikely to recur
- Duplicating an existing rule

## Step 4: Show Proposed Changes

For each proposed addition, show:

````markdown
### Update: ./AGENTS.md

**Why:** <one-line reason>

```diff
+ <the addition>
```
````

## Step 5: Apply with Approval

Ask if the user wants to apply the changes. Only edit files they approve, preserve existing structure, and keep the update focused on approved additions.
