You ask Cursor to "add a phone field to User."
It greps. It guesses. It finds three files that mention User. It updates two. Breaks one. Misses another.
This is the state of AI-assisted development in 2025.
The problem isn't the AI. It's that your codebase has no map.
The Problem
Your User entity lives in five places:
- Prisma schema
- TypeScript types
- Zod validation
- API endpoints
- Frontend forms
You know this. Your AI doesn't.
So it guesses. Sometimes it's right. Often it's not.
The Fix
What if your codebase had a spec? A single source of truth that said: "User is defined here, validated here, exposed here."
That's Cartographer.
# .graph/entities/user.yaml
name: User
fields:
- name: email
type: string
unique: true
code_refs:
model: "@graph:User.model"
types: "@graph:User.types"
validation: "@graph:User.validation"
You add anchor comments to your code:
// @graph:User.model
export class User {
email: string;
}
// @end:User.model
Now run cartographer scan. It tells you what's in sync. What's missing. What's orphaned.
Connect it to your AI via MCP. Now when you say "add phone to User," it queries the spec. Knows every location. Updates all of them.
No grep. No guessing.
Why This Matters
Code-first documentation dies. Everyone knows this.
Spec-first development works. The spec is the map. The code follows the map. The AI reads the map.
Architecture-as-Code.
Status
Building this now. Core works:
- Entity schemas with Zod validation
- Anchor scanner
- MCP server with tools
- CLI (init, scan, serve)
Next: relations between entities, impact analysis, migration generation.
GitHub: github.com/vyshnavsdeepak/cartographer
Building in public. Feedback welcome.