66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# Autonomous Agent Repository Rules Template
|
|
|
|
This protocol defines the standard structure for a repository's root `AGENTS.md`
|
|
(and symlinked `CLAUDE.md`). It establishes concise behavioral baselines,
|
|
deterministic boundary tiers, and progressive disclosure pointers.
|
|
|
|
## Design imperatives
|
|
|
|
- **Length limit**: Keep the root instruction file concise ($\le 100$ lines target,
|
|
300 lines maximum). Long rule files dilute model attention and are ignored.
|
|
- **Progressive disclosure**: Keep the root file an index of essential build/test
|
|
commands and pointers. Direct deep subsystem knowledge or tutorials into
|
|
specialized documents under `docs/` or `.agents/`.
|
|
- **Deterministic tooling**: Never delegate code formatting, whitespace, or import
|
|
sorting to LLM prompt prose. Formatting and linting belong exclusively to
|
|
deterministic CLI tools (Ruff, Biome, Prettier) run via hooks or CI.
|
|
|
|
## Three-tier operational boundaries
|
|
|
|
Root repository instructions must establish three explicit operational tiers:
|
|
|
|
### 1. ALWAYS (Autonomous Execution)
|
|
Actions the agent must execute autonomously without asking for confirmation:
|
|
- Run targeted local unit and regression tests after making code changes.
|
|
- Execute deterministic linters and formatters before staging files.
|
|
- Update relevant documentation and architectural records when public interfaces change.
|
|
- Follow existing repository patterns, conventions, and module structure.
|
|
|
|
### 2. ASK FIRST (Human Confirmation Required)
|
|
Boundary actions requiring explicit confirmation before invocation:
|
|
- Modifying database schemas or executing destructive data migrations.
|
|
- Introducing new third-party dependencies, packages, or external services.
|
|
- Altering production deployment configurations, Dockerfiles, or CI workflows.
|
|
- Deleting existing tracked source files or removing deprecated public APIs.
|
|
|
|
### 3. NEVER (Non-Negotiable Invariants)
|
|
Hard negative constraints that must never be violated under any circumstances:
|
|
- Never commit plain-text credentials, tokens, or environment files (`.env`).
|
|
- Never force-push (`git push --force` or `-f`) to any remote tracking branch.
|
|
- Never execute destructive git resets (`git reset --hard` or `git clean -f`) on uncommitted work.
|
|
- Never commit directly to primary branches (`main` or `master`).
|
|
- Never suppress compiler warnings or type errors with blanket ignores (`# noqa`, `@ts-ignore`).
|
|
|
|
## Canonical AGENTS.md template
|
|
|
|
```markdown
|
|
# [Project Name] Agent Rules
|
|
|
|
## Stack & Commands
|
|
- Language & Runtime: [e.g. Python 3.12 / Node 20 / Rust 1.80]
|
|
- Package Manager: [e.g. uv / pnpm / cargo]
|
|
- Fast Check: [e.g. pytest tests/unit/ / pnpm test / cargo test]
|
|
- Linter & Formatter: [e.g. ruff check --fix && ruff format / pnpm biome check --apply]
|
|
- Type Checker: [e.g. pyright / pnpm tsc --noEmit]
|
|
|
|
## Three-Tier Boundaries
|
|
- **ALWAYS**: Run relevant checks before declaring completion. Run deterministic formatters.
|
|
- **ASK FIRST**: Adding dependencies, altering database schemas, or changing CI/deploy configs.
|
|
- **NEVER**: Direct commits to main, force pushes, hard resets, or committing secrets/.env.
|
|
|
|
## Workflow & References
|
|
- Feature work occurs in isolated git worktrees or dedicated branches.
|
|
- Follow WHAT-WHY-HOW-LEARNINGS telemetry format for commits and pull requests.
|
|
- Subsystem details: see docs/architecture.md and docs/gotchas/.
|
|
```
|