用途
lat-md 技能用于编写和维护 lat.md 文档文件。lat.md 是一种结构化 Markdown，用来描述项目的架构、设计决策和测试规格。当你需要在 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 图表。
仅主体数量本身不足以证明需要图表；对于简短段落或列表即可清晰说明的简单顺序或关系，应省略图表。图表应让用户和后续智能体概览交互。
每个图表应聚焦一个流程，使用可读标签，并在周围散文中用精确的源代码符号链接解释重要决策。优先使用小型概览或多个聚焦图表，而不是一个密集图表。使用围栏 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|the 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/ 目录都有准确的索引
适用场景与限制
该技能适用于创建或编辑 lat.md/ 目录中的章节，以及维护项目架构、设计决策和测试规格文档。限制包括：不重复源代码；不记录提案、计划功能或未来工作（除非用户明确要求或与实现一起起草）；不当作日志或变更记录；不记录无足轻重的实现细节。图表仅在涉及七个以上交互主体且顺序复杂时使用。目前 frontmatter 仅支持 require-code-mention 字段。