124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
# AGENTS.md
|
|
|
|
This file gives general operating guidance for coding agents working in this repository.
|
|
|
|
## Core Principles
|
|
|
|
- Prefer simple, maintainable solutions over clever ones.
|
|
- Preserve existing behavior unless the task explicitly requires a change.
|
|
- Make the smallest reasonable change that fully solves the problem.
|
|
- Keep code readable: clear names, straightforward control flow, and minimal indirection.
|
|
- Treat tests, types, and linting as part of the implementation, not as optional cleanup.
|
|
- Work in small, coherent increments that can be verified and committed cleanly.
|
|
|
|
## Before Making Changes
|
|
|
|
- Inspect the relevant files and local patterns before editing.
|
|
- Identify the narrowest safe change surface.
|
|
- Check whether there are existing tests, scripts, or conventions to follow.
|
|
- Do not assume missing context; infer from the codebase first.
|
|
|
|
## Repo State Preflight
|
|
|
|
- Before starting work, inspect `git status --short`.
|
|
- Treat pre-existing dirty files as user-owned by default.
|
|
- Do not include pre-existing user edits in agent commits unless explicitly approved.
|
|
- If requested work overlaps with user-owned uncommitted files, pause and ask how to proceed.
|
|
- Encourage the user to commit or stash their work before continuing when appropriate.
|
|
|
|
## Implementation Guidance
|
|
|
|
- Match the style and structure already used in the repository.
|
|
- Avoid broad refactors unless necessary to complete the task.
|
|
- Add comments only where intent would otherwise be unclear.
|
|
- Prefer explicit, simple code over premature abstraction.
|
|
- Keep public APIs, file layouts, and naming stable unless the task calls for a change.
|
|
|
|
## Testing Expectations
|
|
|
|
- Create or update tests for every non-trivial behavior change.
|
|
- Prefer tests that prove user-visible or contract-level behavior.
|
|
- Run relevant tests frequently while working.
|
|
- After each meaningful change, run the smallest test scope that gives fast feedback.
|
|
- Before finishing, run broader verification for the touched area.
|
|
- If a change cannot be tested automatically, state that clearly.
|
|
|
|
## Safety Rules
|
|
|
|
- Never overwrite or revert user changes unless explicitly asked.
|
|
- Avoid destructive commands unless clearly requested.
|
|
- Call out assumptions when they materially affect behavior.
|
|
- If you find unrelated problems, note them separately.
|
|
|
|
## Verification
|
|
|
|
- Run the smallest relevant verification after making changes.
|
|
- If tests or checks cannot be run, say so explicitly.
|
|
- Verify both the happy path and the most likely failure path when possible.
|
|
|
|
## Documentation
|
|
|
|
- Re-read `AGENTS.md`, `PLAN.md`, and relevant files in `docs/` before planning or implementing.
|
|
- Update `docs/` when behavior, structure, or standards change.
|
|
- Update `PLAN.md` when work is completed, deferred, or split into follow-up work.
|
|
- Do not consider work complete until code and docs are aligned.
|
|
|
|
## Commit Discipline
|
|
|
|
- Commit work in logical, reviewable increments.
|
|
- Prefer a commit after each completed unit of work that passes verification.
|
|
- Keep commits focused; avoid mixing unrelated changes.
|
|
- Use clear commit messages describing behavior or intent.
|
|
- Do not commit broken work unless explicitly requested.
|
|
|
|
## Branch Discipline
|
|
|
|
- Do new feature work on a dedicated branch.
|
|
- Use a distinct branch per feature, fix, or scoped task.
|
|
- Start new work from `dev` unless specified otherwise.
|
|
- Keep branch names descriptive and scoped.
|
|
- Do not carry unrelated uncommitted changes across branches.
|
|
- Merge completed feature branches into `dev` after verification.
|
|
- Reserve `main` for release-ready code.
|
|
|
|
## AI Metadata
|
|
|
|
- Keep purely agent-only working notes on the `ai` branch unless specified otherwise.
|
|
- Do not mix AI metadata commits with application feature commits.
|
|
- If a file is required for active repo guidance, keep it in the working branch.
|
|
|
|
## Agent Identity
|
|
|
|
- Use a dedicated Git author identity for AI-created commits.
|
|
- Default agent identity:
|
|
- Name: `Codex`
|
|
- Email: `codex@local`
|
|
- Prefer per-commit identity flags:
|
|
- `git -c user.name="Codex" -c user.email="codex@local" commit ...`
|
|
- Do not change the user's global Git identity.
|
|
|
|
## Commit Ownership
|
|
|
|
- The user and agents use separate Git identities.
|
|
- Only agent-authored changes should be included in agent commits.
|
|
- Do not include pre-existing user edits in agent commits unless explicitly approved.
|
|
- If overlap exists, pause and ask before proceeding.
|
|
|
|
## Release And Versioning
|
|
|
|
- Treat `dev` as the active integration branch.
|
|
- Merge `dev` into `main` only for releases.
|
|
- Bump versions only during release preparation unless instructed otherwise.
|
|
- Keep version changes grouped into release commits.
|
|
- Tag releases from `main` when applicable.
|
|
|
|
## Communication
|
|
|
|
- Be concise and concrete.
|
|
- Summarize what changed, why, and how it was verified.
|
|
- Surface risks, tradeoffs, and follow-up work clearly.
|
|
|
|
## Scope
|
|
|
|
- This file is intentionally general.
|
|
- Add stack-specific or workflow-specific guidance as the repository grows. |