From Code Maps to Knowledge Graphs: Generating lat.md
Today lat.md hit Hacker News. It addresses a real problem: AGENTS.md doesn't scale. A single flat file can describe a small project, but as codebases grow, design decisions get buried and agents hallucinate context they should be able to look up.
lat.md solves this with a graph of interconnected markdown files using [[wiki links]]. Sections link to each other, source files link back with @lat: comments, and lat check validates that nothing drifts out of sync. It's essentially Obsidian for your codebase, with enforcement.
The catch: someone has to write those docs. And maintain the links. That's where LLM-assisted authoring comes in.
The pipeline
We already had mapping-codebases, a skill that extracts structural maps from source code via tree-sitter — every function, class, import, and line number, without touching an LLM. The maps show what exists but not why it's shaped that way.
lat.md captures the why. The new generating-lattice skill bridges the two:
Phase 1 — Run mapping-codebases. Zero LLM tokens. Pure AST extraction. Now you have the skeleton.
Phase 2 — Read source selectively, guided by the maps. A 2000-line awards engine often has all its rules in the first 100 lines of constants and the header comment. The maps tell you where to look; you skip the rest.
Phase 3 — Generate lat.md sections with [[wiki links]] cross-referencing concepts and anchoring to source code symbols. Group by domain concept, not file structure.
Phase 4 — lat check validates everything. All links resolve, all leading paragraphs are ≤250 chars, all source code references point to real symbols.
Phase 5 — Set up agent integration: append workflow instructions to CLAUDE.md, add cache .gitignore.
Phase 6 — A bundled script (suggest_backlinks.py) parses the generated wiki links, locates the referenced symbols in source, and suggests where to place @lat: back-link comments. This closes the bidirectional loop.
Testing on a real app
We tested on aeyu.io, a client-side Strava companion PWA with ~8K lines across 16 source files. The result: 7 lat.md files, 269 lines, 71 wiki links (49 into source code symbols), all passing lat check. The back-link script identified 35 missing @lat: annotations with correct symbol locations.
The maps-first approach saved significant tokens. The largest source file (2318 lines of award computation) only needed its header comment and constants — about 100 lines of selective reading instead of the full file.
Maps vs lattice: complementary layers
The two tools address different questions. _MAP.md answers "what's in this codebase?" — structural, automated, zero-cost. lat.md/ answers "why is it shaped this way?" — semantic, curated, cross-referenced. The mapper is reconnaissance; the lattice is institutional memory.
For approaching an unfamiliar codebase: run the mapper first (30 seconds, zero thought), skim the structural map to orient, then use the lattice for design intent. For maintaining a codebase: the lattice captures the invariants and decisions that agents need to respect.
Try it
The skill: generating-lattice
The dependency: mapping-codebases
The tool: lat.md
Example output: aeyu.io/lat.md/