Skip to main content

Module 2: lat.md — grounding your agent

An agent is only as good as what it's grounded in. Ask Claude Code to "follow the existing pattern" in a codebase with no structured documentation, and it's guessing from whatever comments and code it happens to read — which drifts out of date the moment someone refactors without updating a comment. lat.md exists to fix that.

What lat.md is​

lat.md is a cross-linked markdown knowledge graph, kept in a project's lat.md/ directory, that describes what a project does and why — its domain concepts, key design decisions, business logic, and test specs. It's not API documentation and it's not a changelog. It's the architecture and intent that would otherwise live only in a senior engineer's head, or in a design doc nobody links to from the code.

Crucially, lat.md is meant to be kept in sync with the code, not written once and abandoned. That's the whole point of the reinforcement loop described later in this module.

Sections​

A lat.md/ file is organized into sections — headings and subheadings, each with a required leading paragraph that gives its overview. A section is addressed by an id combining the file and heading path, for example:

lat.md/operations#Execution runtime & the two ADW models

That's what lets tooling (and other sections) point at a precise piece of documentation instead of "somewhere in this file."

Sections cross-reference each other with wiki links — double-bracket syntax that names another section (or a piece of source code) as a target. Inside a lat.md/ file, a link looks like this:

See [[architecture#Content-as-code model]] for how tracks are structured,
and [[src/config.ts#getConfigDir]] for where that path is resolved in code.

Two things to notice: a wiki link can point at a documentation section (file#Heading) or directly at a symbol in source code (path/to/file.ts#functionName, or Class#method for a class method). The lat check command (below) validates that every one of these targets actually exists — a link to a renamed or deleted function fails the check.

Don't use this syntax in Academy docs

The double-bracket wiki-link syntax you just saw is only valid inside a project's own lat.md/ files. You will never write it in a Docusaurus page like this one — use ordinary Markdown links instead. It's shown here in a fenced code block purely so you can recognize it when you see it in a project's lat.md/.

@lat: code refs​

The reverse direction — tying a piece of source code back to the concept it implements — is a comment convention, @lat:, placed next to the relevant code:

# @lat: [[tests#LMS Backend#Progress write is idempotent]]
def test_progress_write_is_idempotent():
    ...
// @lat: [[lms-backend#API surface]]
export async function getMe(req: Request) { ... }

This is what lets lat check catch drift in both directions: a spec section with no code reference, or a code reference pointing at a section that no longer exists.

The five commands​

lat search "natural language query"   # semantic search across all sections
lat locate "Section Name"             # find a section by name (exact/fuzzy)
lat check                             # validate all wiki links and code refs
lat refs "file#Section"               # find what references a section
lat expand "some prompt text"         # resolve [[refs]] inside a prompt

In day-to-day use, lat search and lat locate are how you find the right context before writing code — "what does this project already say about X?" — and lat check is how the project enforces that its documentation hasn't drifted from reality. lat refs and lat expand are for tracing dependencies and resolving references inside a prompt, respectively.

Semantic search needs a key

lat search requires an LLM key (LAT_LLM_KEY, LAT_LLM_KEY_FILE, or LAT_LLM_KEY_HELPER) to do embedding-based semantic search. If one isn't configured in your environment, lat locate still works for direct name-based lookups.

The reinforcement loop​

Documentation drifts when nothing forces it to stay current. lat.md's answer is three enforcement layers, from softest to hardest:

  1. Soft — an in-session hook plus a CLAUDE.md checklist that reminds an agent (or you) to update lat.md/ after a change, before wrapping up a task.
  2. Hard — lat check runs as a required CI status check. A pull request that renames or deletes a documented symbol, or breaks a wiki link, fails that check and cannot merge. This runs offline and deterministically — no LLM key needed, because it's validating link structure, not doing semantic search.
  3. Shift-left — a pre-commit hook runs lat check against the committed-to-be state, catching the problem before it ever reaches CI.

That hard gate is what makes lat.md trustworthy as ground truth instead of aspirational documentation: it's mechanically impossible to merge code that silently breaks a documented reference.

The company knowledge atlas​

Each repo's lat.md aggregates into the company knowledge atlas, kept honest by the three-gate reinforcement loop.
Each repo's lat.md aggregates into the company knowledge atlas, kept honest by the three-gate reinforcement loop.

A single repo's lat.md/ describes that repo. The wg-lat-atlas repo goes one level up: it aggregates every registered repo's lat.md/ graph into one portfolio-wide graph, connecting sections within a repo and across repos. A repo "feeds the atlas" by doing two things: committing a valid lat.md/ (one that passes lat check), and being registered as a manifest in the orchestration layer. The portfolio-global graph is itself validated the same way a single repo's is — there's a check that runs at atlas-scope, catching cross-repo drift the same way lat check catches in-repo drift.

Wastey says

The pin matters, too: lat.md is installed at a specific pinned version in every project, never @latest. An upgrade can silently change behavior (this org carries a local patch for one LLM provider that an @latest install would wipe). If you ever need to reinstall it, use the project's restore script rather than npm install -g directly.

Hands-on lab​

Run this in a repo that has a lat.md/ directory (most Wasteology repos do — check your CLAUDE.md's "before starting work" section, which usually tells you to run these commands anyway):

  1. Run lat search "<something relevant to a task you're about to do>" and read the top result's section. Notice whether it changes what you'd have assumed about the design.
  2. Run lat locate "<a section name you already know>" and confirm it resolves to the file and heading you expected.
  3. Run lat check and confirm it passes. If it doesn't, read the failure — it will name a broken link or a missing code reference, not a vague error.
  4. Open one lat.md/*.md file and find a wiki link in it. Follow it manually (open the target file/section) to see what a resolved cross-reference looks like in practice.

For a condensed reference once you've got the hang of this, see the lat.md quick-start in the Company Docs.

Explore: the five lat commands​

Click each command to see what it does and when you'd reach for it.

The five lat commandsInteractive

Click any step to see what happens and who's responsible.

Practice: run the hard gate​

repo root — offline, no LLM key needed
$ lat check▋

Knowledge check​

What does a wiki link like file#Heading#SubHeading (in double brackets) do inside a lat.md file?
Which command is the required, offline, deterministic CI gate?
What does the wg-lat-atlas repo do?
Should you ever run `npm install -g lat.md@latest`?

Next up: Module 3 — Spec-first design.