lat-md

lat.md 编写指南

此技能介绍了编写 lat.md/ 文件时使用的语法、结构规则和约定。每当你需要在 lat.md/ 目录中创建或编辑章节时，请加载此技能。

项目专属的 lat 文档应放在 lat.md/ 中。请勿修改此生成的技能或生成的 AGENTS.md 来记录项目指南：两者均由 lat 工具管理，之后可能会被 lat init 替换。

lat.md 中应包含的内容

lat.md/ 文件描述项目做什么以及为什么——包括领域概念、关键设计决策、业务逻辑和测试规范。它们不会重复源代码。可以将每个章节视为源代码引用回去的锚点。

将 lat.md/ 视为当前已实现状态的精简快照。可以在实现过程中同时在 lat.md/ 中拟定计划，目标是在提交时让文档描述已实现的内容。除此之外，除非用户明确要求，否则请勿将提案、假设性设计和未来工作写入 lat.md/。仅涉及规划的任务不需要更新知识图谱。请勿将其用作日志或变更日志，也不要仅为记录无关紧要的实现细节而扩充文档。

适合作为章节的内容：

• 架构决策及其依据
• 领域概念和业务规则
• API 契约和协议
• 测试规范（测试内容及原因）
• 不明显的约束或不变量

不适合作为章节的内容：

• 逐步讲解代码（代码本身就是讲解）
• 自动生成的 API 文档（请使用工具生成）
• 每次变更的日志或变更日志条目
• 提案、计划中的功能、假设性设计或对未来行为的承诺；除非用户明确要求，或在实现过程中拟定并在提交时描述已实现的行为
• 临时笔记或 TODO
• 不会改变当前状态模型的无关紧要的实现细节

章节结构

每个章节必须以一段引言开头——标题后必须立即至少有一个句子，且前面不能有子标题或其他块级内容。

第一段不得超过 250 个字符（不计入 [[wiki link]] 内容）。这段文字用于标识章节——它会出现在搜索结果、命令输出和 RAG 上下文中。

# 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

This is invalid — "Bad Section" has no leading paragraph.

lat check 会强制执行此规则。

图表

默认使用文字描述。只有当概念涉及七个以上相互作用的对象（例如组件、状态或阶段），且具有复杂的顺序、分支或依赖关系，难以仅用文字清楚说明时，才使用 Mermaid 图表。

对象数量本身并不足以构成使用图表的理由；如果简短的段落或列表就能清楚说明简单的顺序或关系，请省略图表。图表应帮助用户和后续 Agent 概览各对象之间的交互。

每张图表都应聚焦于一个流程，使用易读的标签，并在周围的文字中通过精确的源代码符号链接解释重要决策。优先使用小型概览图或多张聚焦的图表，而不是一张密集的图表。请使用围栏式 mermaid 代码块，并运行 lat check 验证语法和可读性。

章节 ID

章节通过文件路径和标题链定位：

• 完整形式：lat.md/path/to/file#Heading#SubHeading
• 简写形式：file#Heading#SubHeading（文件名不重复时）

示例：lat.md/tests/search#RAG Replay Tests、cli#init、parser#Wiki Links。

配置的外部来源使用 [[handle:path/to/file.md#Heading]] 引用 Markdown 标题，使用 [[handle:path/to/file.ts#symbol]] 引用受支持的代码符号。克隆外部来源前，请运行 lat external show <handle>；其输出包含固定的提交版本和安全的检出建议。

Wiki 链接

使用 [[target]] 或 [[target|alias]] 交叉引用其他章节或源代码。

记录已实现的行为时，优先链接最相关的源代码符号，而不是整个文件。讨论整个模块或资源时，或没有受支持的符号可代表目标时，使用整个文件或目录链接。如果正文中提到了某个符号，请直接链接该符号。

章节链接

章节链接可关联相关概念，同时明确其稳定的图谱标识。

See [[cli#init]] for setup details.
The parser validates [[parser#Wiki Links|wiki link syntax]].

仓库路径链接

引用项目根目录下的任何现有文件或目录，无需片段：

[[schema.sql]]
[[CHANGELOG]]
[[src/components]]

不受支持的格式会通过引用验证，但无法由 Lat 打开。#fragment 需要指向 lat.md/ 章节或受支持的源文件。

源代码链接

引用源文件中的函数、类、常量和方法：

[[src/config.ts#getConfigDir]]          — function
[[src/server.ts#App#listen]]            — class method
[[lib/utils.py#parse_args]]             — Python function
[[src/lib.rs#Greeter#greet]]            — Rust impl method
[[src/app.go#Greeter#Greet]]            — Go method
[[src/app.h#Greeter]]                   — C struct

如果正文提到了某个实现符号或由其控制的行为，请链接该符号，而不是使用单独的代码片段或照抄其字面值。优先使用 [[src/config.ts#DEFAULT_TIMEOUT]]（或 [[src/config.ts#DEFAULT_TIMEOUT|默认超时时间]]），而不是单独的标识符或照抄的值。在正文中保留行为说明；该链接可导航至其实现，并验证绑定关系。

lat check 会验证所有目标是否存在。

代码引用

使用 @lat: 注释将源代码关联到 lat.md/ 章节：

// @lat: [[cli#init]]
export function init() { ... }

# @lat: [[cli#init]]
def init():
    ...

支持的注释样式：//（JS/TS/Rust/Go/C/PHP）和 #（Python/PHP）。

每个章节在相关代码处放置一条 @lat: 注释，而不是放在文件顶部。

测试规范

在 lat.md/ 文件中将测试描述为章节。添加 frontmatter，要求每个叶子章节都必须在测试代码中有对应的 @lat: 注释：

---
lat:
  require-code-mention: true
---
# Tests

Authentication test specifications.

## User login

Verify credential validation and error handling.

### 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.

每个测试都引用其规范：

# @lat: [[tests#User login#Rejects expired tokens]]
def test_rejects_expired_tokens():
    ...

规则：

• require-code-mention: true 下的每个叶子章节都必须恰好由一条 @lat: 注释引用
• 每个章节都必须有说明——至少用一句话解释测试验证的内容及原因
• lat check 会标记未被引用的规范和悬空的代码引用

Frontmatter

lat.md/ 文件顶部可选的 YAML frontmatter：

---
lat:
  require-code-mention: true
---

目前唯一受支持的字段是 require-code-mention，用于强制执行测试规范要求。

验证

编辑 lat.md/ 文件后，务必运行 lat check。它会验证：

• 所有 wiki 链接都指向现有章节、仓库路径或源代码符号
• 所有相对 Markdown 链接都指向现有文件
• 完整和折叠的引用式链接都有定义
• 所有 @lat: 代码引用都指向现有章节
• 每个章节都有开头段落（≤250 个字符）
• 所有 require-code-mention 叶子章节都在代码中有引用
• 每个 lat.md/ 目录都有准确的索引