Compact AGENTS.md
Explicit rules for ownership, public surfaces, composition, and allowed imports. Keep them beside the code your agent writes.
For developers building with coding agents
Give your Python
agent boundaries.
Keep building.
AGENTS.md, a blank Python starter, and a starting prompt. Give your agent explicit rules for where code belongs and which parts may connect.
Pilot release — exploring how coding agents apply architecture rules in practice. Your feedback will help shape the kit.
Free for individual use. When sharing the kit, credit Bounded Software Architecture, link back, and include the license.
01 Give each concept an owner.
02 Declare the connections.
03 Check the actual imports.
For coding agents
Full reference.
Compact instructions.
Keep the architecture rules close to the task. The instructions describe business ownership, public command surfaces, private implementation, and composition at application entries.
From reference to prompt
Start with the full reference
A detailed architecture guide and working reference applications.
How we evaluate
Put the boundaries to the test.
Give a coding agent a business case, a starter, and AGENTS.md. Build a fresh application. Then evaluate the code it actually produced.
- 01Business case + starter +
AGENTS.md - 02Fresh application build
- 03Captured application source
Functionality
Business tests and real application entry points.
BSA structure
Ownership, public surfaces, allowed imports, and cycles.
Delivery checks
Application tests, type checks, linting, and formatting.
Design quality
Independent review of application source, supplied tests, and generated tests.
Mutation testing
Break the rules on purpose.
In a disposable copy, we inject a forbidden import. Tach must reject that connection under the declared rules. Supported public imports must still pass. The separate BSA checker examines source ownership and boundaries.
Illustrative import probes
- Declared public surface Allowed
- Another owner’s private command Rejected
- Dependency in the reverse direction Rejected
Inside the instructions
Read the rules. Bring your own requirements.
A closer look at the instructions your coding agent will work with.
AGENTS.md · excerpt
- Capability roots export selected domain types, values, and errors from their
own concept modules, never application operations, commands, handlers, factories,
HTTP routes, or child boundaries.
A capability with command-backed operations exposes its frozen command values
through `commands.py`.
That surface only re-exports its own commands, never handlers. The application
root is a namespace; concept modules never import command surfaces or operations.Inside the download
Instructions you can read.
A project you can make your own.
Get AGENTS.md, a blank Python project, and PROMPT.md in one ZIP. Your agent builds the application from your requirements.
A blank Python starter
Python 3.12 configuration and a lockfile, with pytest, Ruff, Pyright, and Tach as development tools. Add the application your requirements need.
Your starting prompt
A prompt with space for your business requirements. Ask your agent to build your application, its tests, and its connection map.
Before you start
Know what
you’re getting.
Who is this for?
Python developers who want explicit ownership and import rules while working with coding agents. You should be comfortable running a Python project and its checks.
Does it work with my coding agent?
The instructions are Markdown. Use them with an agent that reads AGENTS.md, or supply them through your tool’s project-instruction mechanism. Behavior varies by tool and model; universal compatibility has not been established.
How does this help as my codebase grows?
Give your coding agent a consistent set of rules for where code belongs and how different parts connect. Keep ownership clear as you add features.
How are module boundaries checked?
The starter includes Tach. Your agent declares allowed dependencies and public interfaces in tach.toml, then checks the application’s imports against those rules. Tach can also export a Mermaid dependency diagram so you can inspect the connections. Review ownership and business responsibilities alongside the checks.
What about the license, updates, and support?
Free for individuals building their own projects, including commercial projects. Use on behalf of an employer or business client requires a separate license. You may sell the applications you build. Consulting is available by separate agreement. Read the full license ↗
The Python architecture kit
Give your agent
a starting point.
Read the instructions. Add your requirements. Build your own Python application.
FreeIndividual use
Download the Python kit