ggbuild
AGENTS.md2 starsChanged 2 months agoApache-2.0View on GitHub
%% lat:begin %% # Before starting work Use Lat's knowledge graph to ground each task before changing code. After EVERY task, before responding to the user: Lat.md is the project's structured knowledge graph for architecture, design decisions, behavior, and tests. The graph lives in lat.md/ as cross-linked Markdown describing what the project does and why. Use it to ground work in actual architecture, and keep it a focused current/planned snapshot rather than a journal or changelog. Project-specific lat documentation belongs…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- lat-mdSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 4
Use Lat's knowledge graph to ground each task before changing code.
- Very specific: line 6
Run lat search to find sections relevant to your task.
- Very specific: line 7
Run lat expand on user prompts to expand any [[refs]] — this resolves section names to file locations and provides context.
- Distinctive: line 11
After EVERY task, before responding to the user:
- Distinctive: line 29
Use these commands to navigate, expand, and validate the project knowledge graph.
- Very specific: line 40
Run lat --help when in doubt about available commands or options.
- Distinctive: line 77
Every section MUST have a description — at least one sentence explaining what the test verifies and why.
- Very specific: line 90
Do not duplicate refs. One @lat: comment per spec section, placed at the test that covers it.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
%% lat:begin %%
Before starting work
Use Lat's knowledge graph to ground each task before changing code.
- Run
lat searchto find sections relevant to your task. Read them to understand the design intent before writing code. - Run
lat expandon user prompts to expand any[[refs]]— this resolves section names to file locations and provides context.
Post-task checklist (REQUIRED — do not skip)
After EVERY task, before responding to the user:
- Update
lat.md/if you added or changed meaningful functionality, architecture, tests, behavior, or planned work. Keep it a focused snapshot of current/planned state, not a journal/changelog. - Run
lat check— all validations must pass - Do not skip these steps. Do not consider your task done until both are complete.
What is lat.md?
Lat.md is the project's structured knowledge graph for architecture, design decisions, behavior, and tests.
The graph lives in lat.md/ as cross-linked Markdown describing what the project does and why. Use it to ground work in actual architecture, and keep it a focused current/planned snapshot rather than a journal or changelog.
Project-specific lat documentation belongs in lat.md/. Do not modify this generated instruction file or a generated lat-md SKILL.md to record project guidance: both are owned by lat tooling and may be replaced by a later lat init.
Commands
Use these commands to navigate, expand, and validate the project knowledge graph.
lat locate "Section Name" # find a section by name (exact, fuzzy)
lat refs "file#Section" # find what references a section
lat search "natural language" # semantic search across all sections
lat expand "user prompt text" # expand [[refs]] to resolved locations
lat external show <handle> # inspect a pinned external source before cloning it
lat check # run full graph and documentation validationRun lat --help when in doubt about available commands or options.
If lat search fails because no API key is configured, explain to the user that semantic search requires a key provided via LAT_LLM_KEY (direct value), LAT_LLM_KEY_FILE (path to key file), or LAT_LLM_KEY_HELPER (command that prints the key). Supported key prefixes: sk-... (OpenAI) or vck_... (Vercel). If the user doesn't want to set it up, use lat locate for direct lookups instead.
Syntax primer
Lat uses stable section ids, wiki links, source links, and code references to connect documentation with implementation.
- Section ids:
lat.md/path/to/file#Heading#SubHeading— full form uses project-root-relative path (e.g.lat.md/tests/search#RAG Replay Tests). Short form uses bare file name when unique (e.g.search#RAG Replay Tests,cli#search#Indexing). - Wiki links:
[[target]]or[[target|alias]]— cross-references between sections. Can also reference source code:[[src/foo.ts#myFunction]]. - Source code links: Wiki links in
lat.md/files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path:[[src/config.ts#getConfigDir]],[[src/server.ts#App#listen]](class method),[[lib/utils.py#parse_args]],[[src/lib.rs#Greeter#greet]](Rust impl method),[[src/app.go#Greeter#Greet]](Go method),[[src/app.h#Greeter]](C struct).lat checkvalidates these exist. - Code refs:
// @lat: [[section-id]](JS/TS/Rust/Go/C) or# @lat: [[section-id]](Python) — ties source code to concepts
Test specs
Key tests can be described as sections in lat.md/ files (e.g. tests.md). Add frontmatter to require that every leaf section is referenced by a // @lat: or # @lat: comment in test code:
---
lat:
require-code-mention: true
---
# Tests
Authentication and authorization test specifications.
## User login
Verify credential validation and error handling for the login endpoint.
### Rejects expired tokens
Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
### Handles missing password
Login request without a password field returns 400 with a descriptive error.Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
# @lat: [[tests#User login#Rejects expired tokens]]
def test_rejects_expired_tokens(): ...
# @lat: [[tests#User login#Handles missing password]]
def test_handles_missing_password(): ...Do not duplicate refs. One @lat: comment per spec section, placed at the test that covers it. lat check will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
Section structure
Concise opening paragraphs give every section a stable overview for validation and discovery.
Every section in lat.md/ must have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding [[wiki link]] content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
# Good Section
Brief overview of what this section documents and why it matters.
More detail can go in subsequent paragraphs, code blocks, or lists.
## Child heading
Details about this child topic.# Bad Section
## Child heading
Details about this child topic.The second example is invalid because Bad Section has no leading paragraph. lat check validates this rule and reports errors for missing or overly long leading paragraphs.
%% lat:end %%
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

