From bb55f37fe116373c77606d3db93253667b3d6d9b Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Fri, 13 Feb 2026 22:25:12 -0500 Subject: [PATCH] Refactor AGENTS and CLAUDE for repo-agnostic guidance --- AGENTS.md | 92 +++++++++++++++++++++++++++---------------------------- CLAUDE.md | 72 +++++++++++++++++++++++++------------------ 2 files changed, 88 insertions(+), 76 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3d6971f..bc24a0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,49 +1,66 @@ # AGENTS.md -Repository-wide instructions for any autonomous or semi-autonomous coding agent. +Repository-wide operating instructions for autonomous and semi-autonomous coding agents. -## Purpose +## Goal -This repository is designed to be reused across many downstream projects. Keep behavior, docs, and naming generic by default unless you are actively working inside a specific downstream repo that requires explicit customization. +Keep this repository reusable across many downstream projects. Favor generic defaults, portable workflows, and minimal assumptions so the same guidance works in different stacks and environments. -## Startup checklist (run every session) +## Session startup checklist -1. Read this file (`AGENTS.md`). -2. Read `CLAUDE.md` for execution conventions. -3. Read `CONTRIBUTING.md` for commit/PR expectations. -4. Check `KNOWN_ISSUES.md` for active blockers or workarounds. +Run this checklist at the beginning of every session: + +1. Read `AGENTS.md` (this file). +2. Read `CLAUDE.md` for execution workflow and handoff rules. +3. Read `CONTRIBUTING.md` for commit and pull request expectations. +4. Read `KNOWN_ISSUES.md` for active blockers and workarounds. 5. Review `docs/agent-handoffs/README.md` and recent notes in: - `docs/agent-handoffs/learnings/` - `docs/agent-handoffs/incidents/` -## Generic-first policy +## Repo-agnostic defaults -- Do not hardcode organization, product, customer, or brand-specific details. -- Do not assume a single deployment environment unless explicitly configured. -- Prefer neutral names such as `project`, `service`, `integration`, `consumer`, `provider`. -- Add project-specific notes only when working in that project’s own repository, and label them clearly. +- Do not hardcode company, product, customer, environment, or team-specific details. +- Prefer neutral terms such as `project`, `service`, `consumer`, `provider`, `integration`, and `environment`. +- Avoid assumptions about deployment target (local, cloud, CI, container) unless explicitly configured. +- Add project-specific details only when required by the current repository and clearly label them as such. -## Agent learning + handoff protocol +## Decision and implementation policy -Agents are expected to leave concise, reusable notes so future agents do not need to rediscover the same context. +- Start with the smallest safe change that solves the user request. +- Prefer explicit commands over implied behavior. +- Keep edits focused; avoid unrelated refactors. +- Preserve backward compatibility unless the task explicitly allows breaking changes. +- If uncertainty remains, document assumptions in the final summary. -### Which file should be updated? +## Validation baseline -- Update `KNOWN_ISSUES.md` when an issue is active/reproducible and others may hit it. -- Add a file in `docs/agent-handoffs/learnings/` for reusable successful patterns. -- Add a file in `docs/agent-handoffs/incidents/` for failures, root cause, and mitigations. +- Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts). +- If a check cannot run due to environment limits, record: + - what was attempted, + - why it could not run, + - what fallback validation was done. +- Never claim a check passed if it was not executed. -### Naming convention +## Agent handoff protocol + +Capture reusable context so future agents can continue without rediscovery. + +### Where to record information + +- `KNOWN_ISSUES.md`: active/reproducible issues, current status, impact, and workarounds. +- `docs/agent-handoffs/learnings/`: successful patterns or repeatable fixes. +- `docs/agent-handoffs/incidents/`: failures, root causes, and mitigations. + +### Note naming Use generic, descriptive filenames: -- `YYYY-MM-DD-short-topic.md` (example: `2026-02-14-lock-timeout-tuning.md`) +- `YYYY-MM-DD-short-topic.md` -Avoid product, team, or person-specific prefixes. +### Required note sections -### Required note structure - -Each learning/incident note should include: +Every new learning/incident note should include: - Context - Observation @@ -51,29 +68,10 @@ Each learning/incident note should include: - Validation performed - Recommendation for next agents -Keep each note short, actionable, and safe to share (no secrets). +## Priority order for conflicting instructions -### When to write a note - -Write or update a handoff note when you discover: - -- A non-obvious fix or command sequence that works reliably. -- A recurring failure mode and how to prevent it. -- A validation step that catches common mistakes early. - -## Safety and quality baseline - -- Make the smallest safe change first. -- Prefer explicit commands over assumptions. -- Validate with relevant tests/checks. -- If blocked by environment limits, record the blocker and fallback. - -## Priority order - -When instructions conflict, follow this order: - -1. System/developer/user instructions in-session +1. System/developer/user instructions in the active session 2. `AGENTS.md` 3. `CLAUDE.md` 4. `CONTRIBUTING.md` -5. Inline comments and prompt files +5. Inline comments and prompt templates diff --git a/CLAUDE.md b/CLAUDE.md index 78d8a8b..6e9087e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,52 +1,66 @@ # CLAUDE.md -Operational playbook for agent execution in this repository. +Execution playbook for agents working in this repository. ## Scope -Applies to all agent tasks unless superseded by direct runtime instructions. +Applies to all tasks unless overridden by direct session instructions. -## Operating model +## Core operating principles -- Keep output and changes generic by default. -- Prefer deterministic, auditable steps. -- Record useful decisions so future agents can continue with minimal rediscovery. +- Be repository-agnostic by default. +- Keep behavior deterministic and auditable. +- Prefer minimal, reversible changes. +- Leave the workspace clearer for the next agent than you found it. -## Execution flow (recommended) +## Recommended execution workflow -1. Read policy files listed in `AGENTS.md` startup checklist. -2. Review current known issues and recent handoff notes. -3. Implement the smallest safe change. -4. Validate with relevant checks/tests. -5. Update shared docs (`KNOWN_ISSUES.md` and/or handoff notes) when new reusable knowledge appears. +1. Load baseline context from `AGENTS.md`, `CONTRIBUTING.md`, `KNOWN_ISSUES.md`, and handoff notes. +2. Restate the task internally as concrete outcomes. +3. Make the smallest safe implementation change. +4. Validate with the most relevant automated checks available. +5. Summarize results with clear evidence (commands, outputs, and file references). +6. Record durable learnings/incidents if new reusable knowledge was discovered. -## Handoff documentation workflow +## Change quality checklist -When you learn something that can help future agents: +Before finishing, verify: -1. Check for related notes in: +- The change is scoped to the request. +- Naming and docs remain generic unless project-specific behavior is explicitly required. +- Existing workflows are not silently broken. +- Validation matches the risk level of the change. + +## Handoff and documentation expectations + +When new reusable context appears: + +1. Search for an existing related note in: - `docs/agent-handoffs/learnings/` - `docs/agent-handoffs/incidents/` -2. If the insight is new, add a short markdown note using the naming standard from `AGENTS.md`. -3. If the issue is still active/reproducible, add or update the corresponding entry in `KNOWN_ISSUES.md`. -4. Keep note content sanitized and reusable (no secrets, no user-identifying details). +2. Update existing notes if they already cover the issue. +3. Otherwise add a new note using `YYYY-MM-DD-short-topic.md`. +4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`. + +Keep notes concise, actionable, and safe to share. ## What belongs where -- `KNOWN_ISSUES.md`: active/reproducible issues, impact, workaround, and current status. -- `docs/agent-handoffs/learnings/`: durable implementation insights and successful patterns. -- `docs/agent-handoffs/incidents/`: failure writeups, root causes, and prevention guidance. -- `CONTRIBUTING.md`: standards for proposing, validating, and reviewing changes. +- `KNOWN_ISSUES.md`: active issues, impact, status, workaround, verification date. +- `docs/agent-handoffs/learnings/`: successful implementation patterns. +- `docs/agent-handoffs/incidents/`: failures and prevention guidance. +- `CONTRIBUTING.md`: contribution, review, and quality standards. -## Style for handoff notes +## Writing style for handoff notes - Prefer bullets over long prose. -- Include exact commands where useful. -- State confidence and remaining uncertainty. +- Include exact commands when they improve reproducibility. +- Explicitly separate facts from assumptions. - End with: `Recommendation for next agents:` -## Anti-patterns +## Anti-patterns to avoid -- Avoid repo-local jargon in reusable templates. -- Avoid stale TODO dumps without context. -- Avoid project/brand-specific terms unless explicitly required by the active downstream repo. +- Product/brand-specific assumptions in reusable docs. +- Broad refactors not required for the current request. +- Status updates without validation evidence. +- Duplicated notes that fragment context.