Carta gives them the map. An architectural knowledge graph curated by your team, read deterministically by your agents.
Not a config file, not a wiki, not RAG. Carta is sourced, cross-referenced, and multi-level. Foundations through project, every decision tracked in Git. Plain markdown you open in any markdown reader (we like Obsidian); point your coding agent at the directory and humans and agents read the same files.
Your team curates the map. Your agents traverse it, spending tokens on the work, not redrawing what your team has already settled. The map gets sharper with every commit.
agent.md, not RAG.Out of the box, your coding agent doesn't know how your team builds software. Teams patch that gap in a few ways. Here's how each compares on the things that matter.
| Feature | agent.md |
Wiki | RAG | Carta |
|---|---|---|---|---|
| Scales past one file | ✗ | ✓ | ✓ | ✓ |
| Compounds across the org with every commit | ✗ | ~ | ✗ | ✓ |
| Token-efficient: loads only what the query needs | ✗ | ✗ | ~ | ✓ |
| Cross-referenced, traversable graph | ✗ | ~ | ✗ | ✓ |
| Multi-level overrides (org / team / project) | ✗ | ✗ | ✗ | ✓ |
| Sources cited per node | ✗ | ✗ | ~ | ✓ |
| Deterministic for agents | ✓ | ✗ | ✗ | ✓ |
Each row below pairs a challenge with the design choice that handles it.
A 5-second timeout is right for most services and wrong for a payments processor doing 3D Secure (10–20s). A generic REST shape is right for most teams and wrong if your org has standardised on RFC 7807 errors and /v1/ versioning.
Each more local level overrides or extends the level above, with an ADR explaining why. Your project's pattern-circuit-breaker.payments-api wins; the foundation stays generic. No forks, no duplication.
"Should we use CQRS?" depends on what you're optimising for (performance? consistency?), what kind of system (web app? data pipeline?), and what stage you're at (prototype? production?). Most agent-knowledge skips the framing and just lists patterns.
Pillars (reliability, security, cost, performance, op-ex) frame the trade-off. Contexts (web app, pipeline, agentic, …) scope the system. Stages (prototype → critical) scope the bar. Principles back the patterns. Decision trees resolve alternatives. Same reasoning shape every traversal.
A pattern recommendation is only as good as its provenance. Without sources you can't check the reasoning, can't tell when something was canonical, and can't update when the source updates. "Best practice" without citations is folklore.
Books with chapter references. Papers with DOIs. Canonical articles with URLs. A Currency note when the source is older but the pattern is shape-level. The source list is the test for whether a node deserves to exist.
Want to see the algorithm walk a real codebase? Step through a full /carta-review traversal: six passes against a production payments API, with every node, override, and ADR pulled from the foundation.
Every node carries verifiable sources: books, papers with DOIs, canonical articles. Older sources are admitted only when the author is canonical and the pattern is shape-level, with a Currency note where it matters.
Covering communication, data, resilience, scaling, security, observability, deployment, agentic systems, testing, delivery / CI, frontend. Patterns include Cache-Aside, Circuit Breaker, Idempotency Key, Retry with Backoff, Transactional Outbox, CQRS, Saga, and 90 more.
Install once with a symlink. They all read from $CARTA_PATH, so the same Carta serves every project on your machine.
Single-response traversal: matches contexts, pillars, stage; returns recommended patterns with rationale and citations. No codebase read.
Spawns a subagent that iterates the traversal protocol across six passes (with up to four iterations of the candidate-stability loop), pairing every finding with a file:line citation. Concise by default; verbose on request. See it walk a real codebase →
Reads the project's README, docs, manifests; proposes a profile (slug, context, stage, pillars, detected stack); writes a charter ADR and a tech-stack ADR for review.
Loads the writing rules and the matching template, drafts a terse markdown file (front-matter, decision inputs, when-to-use / when-NOT-to-use, sources), runs the validator and linter. You review, edit, commit.
Fork the repo on GitHub, clone your fork. Foundations stay shared; your org/team/project levels are yours to extend.
Set CARTA_PATH in ~/.claude/settings.json and symlink the commands into ~/.claude/commands/. Full instructions in commands/SETUP.md.
Ask any architectural question. Carta will ask for the system's stage and return recommended patterns, with citations.
# 1. Fork on GitHub, then clone your fork git clone https://github.com/<your-org>/carta.git cd carta # 2. Configure Claude Code (see commands/SETUP.md) # set CARTA_PATH and symlink the commands # 3. From any project /carta choose a caching strategy for our product catalog API /carta-review ./backend /carta-project-setup ./new-service /carta-add pattern for idempotency keys on payment endpoints
Carta is plain markdown in your repo. That means it's yours to maintain. Unlike a wiki or a vector index, the maintenance loop is in your normal review workflow, not a parallel system.
Whoever owns architectural decisions on your team, usually a tech lead or staff engineer, sometimes a small guild. The role is light: spot a recurring decision (in PR review, in an incident, in a /carta answer that didn't quite fit) and turn it into a node.
Expect roughly 20 minutes per node, often less. The output is a small, sourced markdown file, closer to a high-quality ADR than a wiki page.
The closing loop is /carta-add → review → commit. The command loads the matching template and writing rules, drafts a terse node, and runs the validator and linter. You read it, sharpen it, push it through normal code review.
Because Carta lives in Git, every node has an author, a diff, and a commit message. There is no separate publishing step and no separate place to look.
Foundations are MIT-licensed and shared. Your fork pulls them in; your org/, teams/, and projects/ directories are yours alone. Upstream changes arrive via a regular git pull or merge from upstream.
Conflicts surface in your overrides, exactly where you want a human in the loop. We treat foundation drift as a feature, not a hazard.
Carta is pre-1.0 and built in the open. The foundation is MIT-licensed; your organisation, team, and project levels stay yours. The fastest way in is the README, then the quickstart, then a first /carta on something you're already working on.