My presonal AGENTS.md template

AGENTS.md

AGENTS.md

This repository contains a research project/prototype for ...

Start here

When entering this repository, read in this order:

1. README.md
2. docs/whitepaper.md
3. Relevant files in docs/tickets/
4. Relevant files in docs/milestones/

Repository setup

Before making changes, check whether this directory is already a git repository.

If .git/ does not exist, initialize a local git repository:

git init
git add .
git commit -m "Initial repository snapshot"

Before the initial commit, inspect the working tree and avoid committing large data files, caches, credentials, or generated artifacts.

Do not push to a remote repository unless the user explicitly asks.

Document roles

• README.md: setup, purpose, and entry points.
• docs/whitepaper.md: long-term architecture and project memory.
• docs/tickets/: authorized implementation tasks.
• docs/milestones/: design history and completed decisions.
• AGENTS.md: instructions for coding agents.

Working rules

• Follow a strict ticket-first workflow.
• Do not start implementation unless a matching ticket exists in docs/tickets/.
• Stay within the active ticket scope.
• Prefer small, inspectable changes over broad rewrites.
• Prefer deterministic tests and traceable behavior over opaque logic.
• Preserve existing behavior unless the ticket explicitly asks for a change.
• Update relevant documentation when behavior, interfaces, or assumptions change.

AGENTS.md rule

Do not modify AGENTS.md during normal implementation work.

Modify it only when the user explicitly asks, or when the active ticket clearly requires repository-level agent instruction changes.

Keep such changes minimal and explain why they were necessary.

Testing

Unless a ticket explicitly says otherwise, run:

uv run pytest -q

If tests fail, fix them within the same ticket scope before completion.

Git

After implementing a ticket and confirming tests pass:

1. Review the changes.
2. Commit the changes to the local git repository.
3. Do not push to a remote repository.

Use clear commit messages that reference the ticket when possible.