diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c99eea1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,59 @@
+# AGENTS.md
+
+## Project Overview
+
+A Cookiecutter template for Python packages, supporting both CLI and library project types. Generates projects with uv, ruff, pyright, and pytest pre-configured. It also comes with GitHub Actions workflows configured for the project.
+
+This template is opinionated and enforces recommended practices when creating new Python projects.
+
+## Repository Structure
+
+- `{{cookiecutter.project_slug}}/` - Template directory (rendered by Cookiecutter)
+- `cookiecutter.json` - Template variables and prompts
+- `hooks/` - Pre/post generation scripts
+  - `pre_gen_project.py` - Validates inputs (namespace, slug, entry point)
+  - `post_gen_project.py` - Cleans up unused files based on options
+
+## Key Template Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `project_name` | Human-readable name |
+| `project_slug` | Pip/repo name (auto-derived) |
+| `project_namespace_import` | Optional namespace (e.g., `company.tools`) |
+| `repo_type` | `CLI` or `library` |
+| `entry_point` | CLI command name (CLI only) |
+
+## Testing Changes
+
+Generate a test project to verify template changes:
+
+```bash
+# Generate in temp directory
+uvx cookiecutter -o /tmp .
+
+# Or with specific options (no prompts)
+uvx cookiecutter --no-input -o /tmp . project_name="Test Project" repo_type="CLI"
+```
+
+Then verify the generated project:
+
+```bash
+cd /tmp/test-project
+make lint && make test
+```
+
+## Verification
+
+When modifying the template:
+
+1. Ensure Jinja2 syntax is valid in template files
+2. Test both `CLI` and `library` repo types
+3. Test with and without `project_namespace_import`
+4. Verify generated project passes `make lint && make test`
+
+## Commit Messages
+
+- Summary line: max 50 chars (hard limit 72)
+- Body lines: max 72 chars
+- Use Markdown formatting in description
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/{{cookiecutter.project_slug}}/AGENTS.md b/{{cookiecutter.project_slug}}/AGENTS.md
new file mode 100644
index 0000000..b5bfbb7
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/AGENTS.md
@@ -0,0 +1,49 @@
+# AGENTS.md
+
+## Project Overview
+
+{{ cookiecutter.project_description }}
+
+{%- if cookiecutter.repo_type == 'CLI' %}
+This is a command-line application with entry point `{{ cookiecutter.entry_point }}`.
+{%- else %}
+This is a Python library package.
+{%- endif %}
+
+## Stack
+
+- Package manager: uv
+- Build backend: uv_build
+- Linting/formatting: ruff
+- Type checking: pyright
+- Testing: pytest
+- CI: GitHub Actions (lint, test, release{%- if cookiecutter.documentation != 'none' %}, docs{%- endif %})
+
+## Commands
+
+Use Makefile targets, not tool commands directly:
+
+- `make format` - Fix formatting issues
+- `make lint` - Run all static checks (ruff, pyright)
+- `make test` - Run tests with coverage
+- `make doc` - Generate documentation
+- `make build` - Build the package
+{%- if cookiecutter.entry_point %}
+- `make run` - Run the CLI (use `ARGS="..."` for arguments)
+{%- endif %}
+
+## Verification
+
+Run `make lint && make test` before committing.
+
+## Commit Messages
+
+- Summary line: max 50 chars (hard limit 72)
+- Body lines: max 72 chars
+- Use Markdown formatting in description
+- Reference issues where relevant (e.g., `See #123`)
+
+## Project Layout
+
+- `src/{{ cookiecutter.__project_import.replace('.', '/') }}/` - Source code
+- `test/` - Test files
diff --git a/{{cookiecutter.project_slug}}/CLAUDE.md b/{{cookiecutter.project_slug}}/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md