Advanced Atlas

Advanced Project Atlas

The Project Atlas is a collection of high-density context maps that provide the "source of truth" for the AI.

The Standard Maps

When you run /setup, the framework generates 5 core files in .amanah/atlas/:

• product.md: Domain overview and user roles.
• tech.md: The specific versions of your stack (FastAPI, React, PostgreSQL).
• structure.md: Annotated directory tree (Where things live).
• conventions.md: Your coding standards (Gotchas, naming, import order).
• quickstart.md: Copy-paste recipes for common tasks in your specific repo.

Custom Subsystem Maps

For complex projects, a single Atlas is not enough. You can create custom maps for specific domains:

.amanah/atlas/
├── auth-system.md     # Deep dive into your JWT/OAuth flow
├── billing-engine.md  # Details of Stripe integration and ledger logic
└── data-pipeline.md   # Schema and transformation rules

The generator is programmed to read all .md files in the .amanah/atlas/ directory during the research phase.

Best Practices for Developers

1. The 120-Line Rule

Keep every Atlas file under 120 lines. AI models perform best with high-density, low-noise context. If a map gets too big, split it into a custom map.

2. Focus on "The Delta"

Don't describe what a "React component" is. Describe how your React components are structured (e.g., "We use Functional Components with Tailwind and never use CSS modules").

3. Verification

Run /atlas whenever you make significant structural changes. This ensures the AI's "mental map" of your project stays updated.

4. Human-Readable, AI-Executable

Write Atlas files that a senior developer could use to onboard. If a human can't understand it, the AI will likely hallucinate.