KOKO\Mimi
109 lines
4.4 KiB
Markdown
109 lines
4.4 KiB
Markdown
---
|
|
name: revising-agents-md
|
|
description: Use when a user explicitly asks to capture durable learnings from the current session in AGENTS.md after discovering reusable commands, conventions, validation steps, architecture facts, environment constraints, or recurring gotchas.
|
|
---
|
|
|
|
# Revise AGENTS.md
|
|
|
|
## Overview
|
|
|
|
Turn verified session discoveries into concise Codex guidance for future work.
|
|
Keep only durable information, place it at the narrowest scope where it
|
|
governs work, show the proposed diff, and obtain approval before editing.
|
|
|
|
## Workflow
|
|
|
|
1. **Reflect.** Extract candidate commands, conventions, validation steps,
|
|
architecture relationships, environment constraints, and recurring
|
|
gotchas from the current session.
|
|
2. **Inspect evidence.** Read the relevant repository files and existing
|
|
`AGENTS.md` or `AGENTS.override.md` chain. Check Git tracking and ignore
|
|
state when deciding whether guidance is shared or personal. Treat a claim
|
|
as verified only when supported by a safe command result, repository file,
|
|
or explicit user confirmation.
|
|
3. **Classify every candidate.** Record `candidate`, `keep/exclude`,
|
|
`evidence`, `destination`, and `reason`. Exclude content already documented
|
|
accurately.
|
|
4. **Filter aggressively.** Exclude secrets, credentials, personal data,
|
|
unverified claims, generic advice, facts obvious from code, one-off fixes,
|
|
temporary state, and session narrative. Never reproduce a sensitive value,
|
|
even in an exclusion explanation.
|
|
5. **Choose the narrowest durable scope.**
|
|
- Codex-home `AGENTS.md`: cross-repository personal preferences, only when
|
|
the user explicitly requests global scope.
|
|
- Repository-root `AGENTS.md`: guidance true for work across the repository.
|
|
- Nested `AGENTS.md`: guidance true only for one package, service, feature,
|
|
or subtree.
|
|
- `AGENTS.override.md`: only when the user explicitly requests replacement
|
|
semantics at that directory.
|
|
|
|
Scope follows the code or work governed by the instruction, not the
|
|
directory from which its command must run. A payment-only test command
|
|
belongs in payments guidance even when it says to run from repository root.
|
|
6. **Draft grouped diffs.** For each destination, show a one-line reason and
|
|
the exact minimal diff. Prefer one line per concept and preserve the
|
|
existing file's structure.
|
|
7. **Request approval.** End with an explicit question asking which proposed
|
|
changes the user wants applied. Do not create or edit a file before the
|
|
user approves its exact destination and content.
|
|
8. **Apply and verify.** Edit only approved destinations. Re-read the resulting
|
|
instruction chain, check conflicts and duplication, and verify changed
|
|
commands and paths.
|
|
|
|
## Required Proposal
|
|
|
|
```markdown
|
|
## Session Learning Review
|
|
|
|
| Candidate | Decision | Evidence | Destination | Reason |
|
|
| --- | --- | --- | --- | --- |
|
|
| ... | Keep/Exclude | ... | path or none | ... |
|
|
|
|
### Update: path/to/AGENTS.md
|
|
**Why:** one durable, evidence-backed reason
|
|
|
|
```diff
|
|
+ concise instruction
|
|
```
|
|
|
|
No files were edited. Which proposed changes should I apply?
|
|
```
|
|
|
|
When no candidate qualifies, say so and do not propose an empty file.
|
|
|
|
## Quick Reference
|
|
|
|
| Candidate | Decision |
|
|
| --- | --- |
|
|
| Verified recurring command | Keep at the scope whose work uses it |
|
|
| Package-only gotcha | Keep in that package's nested `AGENTS.md` |
|
|
| Personal preference | Global only after explicit global request |
|
|
| Existing accurate instruction | Exclude as duplicate |
|
|
| One-off fix or session history | Exclude |
|
|
| Generic best practice | Exclude |
|
|
| Unverified claim | Exclude or verify safely first |
|
|
| Secret or personal data | Exclude without reproducing the value |
|
|
|
|
## Example
|
|
|
|
A session verifies `npm run test:payments` and proves it must run from the
|
|
repository root. If only payment work needs that command, propose this in
|
|
`services/payments/AGENTS.md`:
|
|
|
|
```diff
|
|
+- Run `npm run test:payments` from the repository root.
|
|
```
|
|
|
|
Do not place it at repository root merely because that is the execution
|
|
directory.
|
|
|
|
## Common Mistakes
|
|
|
|
- Saving everything because the session was difficult or time-consuming.
|
|
- Confusing command execution location with instruction scope.
|
|
- Creating an override for ordinary additive guidance.
|
|
- Duplicating an instruction that is already accurate.
|
|
- Persisting unverified deployment or environment claims.
|
|
- Showing a diff without explicitly asking for edit approval.
|
|
|