| name | architecture |
| description | Use when setting up a project's structure, or when the agent needs the stack, folder layout, data flow, schemas, and the hard boundary rules it must never cross. Use when code keeps crossing layers (UI logic in API routes, DB calls in components). |
architecture
Overview
Once the agent knows WHAT to build (project-overview), it needs to know HOW it's built. This file is the system's shape plus the boundary rules the agent may never violate — the contract review checks against.
Lives at context/architecture.md.
When to use
- Setting up a new project's structure.
- When layers are bleeding into each other and you need to lock the boundaries.
What goes in it
- Stack — frameworks, language, services, and why each.
- Folder structure — where everything lives.
- System boundaries + data flow — how a request moves through the system.
- Database schemas — tables/collections and relationships.
- Boundary rules the agent must NEVER violate, e.g.:
- API routes contain no UI logic.
- Components contain no DB logic.
- Agent code never imports from components or actions.
- Server actions never call agents.
How to maintain
Add a rule the moment you catch a boundary violation you don't want repeated. The rules are the highest-value part — they're what keeps a codebase coherent at scale.
Common mistakes
- Documenting structure but no rules → the agent will cross layers. The rules are the point.
- Rules the agent can't check → make each one concrete and falsifiable so
review can verify it.
