Domain-Driven Structure

Group by feature/domain, not by file type alone. One feature = one ingestible context chunk.

Feature-first layout

If you are building tenant routing for a CRM, keep in one folder:

• Route handlers / API logic
• UI components for that feature
• Schema or types used only by that feature
• Tests for that feature
• 000-architecture.md primer at the folder root

The agent reads one directory and understands the whole feature.

Localized primers

Name architecture docs 000-feature-architecture.md so they sort first when an agent scans a folder. Each primer should include:

• What the feature does
• Key files and environment variables
• Routes or entry points affected
• How to verify the change

Root vs. feature rules

• Root: .cursor/rules/ or AGENTS.md — stack-wide boundaries
• Feature folder: 000-architecture.md — feature-specific context

Separate content from logic

Content (copy, assets, datasets)	Logic (templates, components, scripts)
Markdown / MDX collections	Page and layout files
Static assets	Component implementations
CMS or data JSON	Build and deploy config

Do not embed massive copy blocks or datasets inside template logic files.

Anti-patterns

• Splitting one feature across 10 unrelated directories
• Duplicating config strings outside a central data module
• Inline thousand-line samples in page templates