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
• 現在の状態モデルを変えない、重要でない実装の詳細

セクションの構造

すべてのセクションには、冒頭の段落が必須です。見出しの直後に、子見出しやその他のブロックコンテンツより前に、少なくとも1文を記述してください。

最初の段落は、[[wiki link]] の内容を除いて250文字以下にしてください。この段落はセクションの識別情報となり、検索結果、コマンド出力、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 図は、複雑な順序、分岐、依存関係があり、文章だけでは追いにくい、7つを超える要素（コンポーネント、状態、段階など）が相互に作用する概念に限って使用してください。

要素数だけを理由に図を使う必要はありません。短い段落やリストで明確に説明できる単純なシーケンスや関係は、図にしないでください。図は、ユーザーや後続のエージェントが相互作用の概要を把握するためのものです。

各図では1つのプロセスに焦点を当て、読みやすいラベルを使ってください。重要な判断については、周囲の文章でソースシンボルへの正確なリンクとともに説明してください。情報量の多い図を1つ作るより、小さな概要図や、焦点を絞った複数の図を優先してください。フェンス付きの 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。

設定済みの外部ソースでは、Markdown の見出しに [[handle:path/to/file.md#Heading]] を、対応するコードシンボルに [[handle:path/to/file.ts#symbol]] を使用します。外部ソースをクローンする前に lat external show <handle> を実行してください。出力には固定されたコミットと、安全なチェックアウト方法の提案が含まれます。

Wiki リンク

[[target]] または [[target|alias]] を使って、他のセクションやソースコードを相互参照できます。

実装済みの動作を記述する場合は、ファイル全体へのリンクよりも、関連する最小範囲のソースシンボルへのリンクを優先してください。モジュールやリソース全体について説明する場合、または対象を表すサポート対象のシンボルがない場合は、ファイル全体またはディレクトリへのリンクを使用してください。文章中でシンボルに言及する場合は、そのシンボルに直接リンクしてください。

セクションへのリンク

セクションへのリンクを使うと、安定したグラフ ID を明示しながら、関連する概念を結び付けられます。

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: コメントを1つ配置し、ファイルの先頭ではなく、関連するコードの位置に記述してください。

テスト仕様

lat.md/ ファイル内のセクションとしてテストを記述します。フロントマターを追加して、すべての末端セクションに対応する @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: コメントからちょうど1回参照されている必要があります
• すべてのセクションに説明が必要です。テストで検証する内容とその理由を説明する、少なくとも1文を記述してください
• lat check は参照されていない仕様と、リンク先のないコード参照を検出します

フロントマター

lat.md/ ファイルの先頭に記述できる任意の YAML フロントマターです。

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

現在サポートされているフィールドは、テスト仕様を適用する require-code-mention のみです。

検証

lat.md/ ファイルを編集したら、必ず lat check を実行してください。次の項目が検証されます。

• すべての Wiki リンクが既存のセクション、リポジトリパス、またはソースコードシンボルを指している
• すべての相対 Markdown リンクが既存のファイルを指している
• 完全形式および省略形式の参照スタイルリンクに定義がある
• すべての @lat: コード参照が既存のセクションを指している
• すべてのセクションに先頭の段落がある（250 文字以内）
• require-code-mention が指定されたすべての末端セクションがコードから参照されている
• すべての lat.md/ ディレクトリに正確なインデックスがある