From 5b9396a1977faf8f795c59f5ce7a0e91091a3c02 Mon Sep 17 00:00:00 2001 From: rharper105 Date: Thu, 9 Apr 2026 17:57:23 -0400 Subject: [PATCH] docs: add AGENTS.md for AI coding agent context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an AGENTS.md file with project conventions, constraints, hub files, and build commands. Helps AI coding agents (Claude Code, Cursor, Codex) understand project patterns before making changes. Generated with: npx sourcebook init Review and edit — the best context comes from human + machine together. --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2b4caf9b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,45 @@ +# AGENTS.md + +Agent instructions for this repository. +Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together. + +## Constraints + +These constraints MUST be followed when modifying this codebase: + +- **Project structure:** This is a publishable library, not an application. Focus changes on the public API surface. Avoid breaking changes to exported types and function signatures. +- **Core modules:** Hub files (most depended on): src/flask/globals.py (imported by 24 files); src/flask/helpers.py (imported by 24 files); src/flask/signals.py (imported by 20 files); src/flask/__init__.py (imported by 9 files); src/flask/sansio/scaffold.py (imported by 9 files). Changes here have the widest blast radius. +- **Circular dependencies:** Circular import chains detected: flask/__init__.py; flask/__init__.py → app.py; flask/__init__.py → app.py → ctx.py. Avoid adding to these cycles. + +## Stack + +Flask + +## Core Modules (by structural importance) + +- `src/flask/globals.py` +- `src/flask/helpers.py` +- `src/flask/signals.py` +- `src/flask/__init__.py` +- `src/flask/json/__init__.py` + +## Conventions + +- **Testing:** Tests live in a separate test/ directory, mirroring src/ structure. New tests go there, not next to source files. +- **Python conventions:** Uses __init__.py as barrel exports. Import from the package, not from internal modules. +- **Dominant patterns:** API endpoints use Flask routes. Follow this pattern for new routes. +- **Dominant patterns:** Tests use pytest. Test utilities in: tests/test_helpers.py. + +## Additional Context + +- Most active areas in the last 30 days: .github/ (6 changes). Expect ongoing changes here. + +## What to Add Manually + +The most valuable context is what only you know. Add: + +- Architectural decisions and why they were made +- Past incidents that shaped current conventions +- Deprecated patterns to avoid in new code +- Domain-specific rules or terminology +- Environment setup beyond what .env.example shows