add harness framework

2026-08-28 00:34:51 +09:00
parent cec7b9bd48
commit 0adb9c26a9
36 changed files with 3500 additions and 0 deletions
@@ -0,0 +1,108 @@
+---
+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.
+
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Revise AGENTS.md"
+  short_description: "Capture durable Codex session learnings safely"
+  default_prompt: "Use $revising-agents-md to propose durable AGENTS.md updates from this session."
+policy:
+  allow_implicit_invocation: false