---
type: reference
topic: architecture
audience: [human]
---

# ドキュメントスタイルガイド

人間と reyn Skill の両方が依存できるドキュメントを書くためのルールです。

## Frontmatter は必須

`docs/` 配下のすべてのページは YAML frontmatter で始まる必要があります:

```yaml
---
type: tutorial | how-to | reference | concept | adr | agent | landing
topic: dsl | runtime | cli | stdlib | config | architecture | getting-started
applies_to: [skill.md, phase.md]   # 任意。このドキュメントが対象とする具体的なファイル/コマンド
audience: [human, agent]            # 主な読者
---
```

`audience` タグは、最終的に `recall_docs` が呼び出し Skill に関連するコンテンツをフィルタリングするために使います。正確に設定してください。

## ファイルの粒度: 1 ファイル 1 コンセプト

agent（およびざっと読む人間）が必要なコンセプトだけを正確に読み込めるようにしてください。無関係な複数のコンセプトを 1 つの長いファイルにまとめないでください。`reference/` ページが約 300 行を超える場合は分割を検討してください。

## Diátaxis の規律

4 つの読み取りモードはそれぞれ異なる役割を持ちます。1 つのドキュメントの中でそれらを混在させないでください。

| モード | 役割 | やってはいけないこと |
|--------|------|---------------------|
| Tutorial | 実践で教える | 網羅的なオプション一覧を書かない |
| How-to | 1 つの問題を解決する | 概念的な脱線をしない |
| Reference | 正確かつ完全であること | チュートリアル風の説明を書かない |
| Concept | 「なぜ」を説明する | ステップバイステップの手順を書かない |

チュートリアルで「なぜそうなるか」を説明したい場合は、インラインで説明せずコンセプトページへリンクしてください。

## クロスリンク

- `docs/` 内では**相対リンク**を使用します（例: `../reference/dsl/skill-md.md`）。
- 前後両方向にリンクしてください: チュートリアルは関連するリファレンスへ、リファレンスはそれを説明するコンセプトへリンクします。
- `reference/stdlib/` 以外からソースファイルへのリンクは避けてください。

## コード例

- リファレンスのコード例はすべて記載どおり実行可能でなければなりません — コピー&ペーストで動作する必要があります。
- チュートリアルのコードは部分的でも構いませんが、省略箇所は明示してください（`# ... rest of file`）。

## 翻訳ポリシー（en ↔ ja）

- **第一言語は英語です。** en 版を先に書いてください。
- **ja はフォールバック対応です。** `mkdocs-static-i18n` はファイルが存在しない場合に en へフォールバックします。準備ができたら翻訳してください。en の更新を ja に待たせる必要はありません。
- **agent/ は en のみです。** あいまいさを低く保つため、agent 向けの指示は翻訳しないでください。
- **changelog/ADR/contributing は en のみです。** 運用ドキュメントです。
- **可能な範囲で同期しますが、ゲートしません。** en ページを変更した場合は、ja ページに TODO コメントを残すかイシューを起票してください。

翻訳時のルール:
- コードブロックはそのまま保持します（変数名、ファイルパス、CLI フラグは翻訳しない）。
- 散文と見出しを翻訳します。
- frontmatter の `topic`/`type` 値は英語のまま保持します（機械可読タグです）。
- 必須ではありませんが、必要に応じて `lang: ja` フィールドを追加できます。

## 用語集

DSL/ランタイム用語は [`docs/en/guide/for-skill-authors/glossary.md`](../../en/guide/for-skill-authors/glossary.md) に記載されています。どちらの言語で書く場合も、その用語集の正規用語名を使用してください。これによりクロスランゲージのクロスリファレンスの一貫性が保たれます。

## ランタイム/DSL のセマンティクスを変更する場合

**3 つすべて**を更新してください:

1. 該当する `reference/` ページ。
2. 「なぜ」が変わった場合は該当する `concepts/` ページ。
3. 同じ制約をコード記述 agent 向けにドキュメント化している場合は `CLAUDE.md`。

これらの 3 つの間のズレが `reference/` が防ぐべき問題ですが、同期を保つ場合に限ります。

## コミット前にローカルでビルドとリントを実行

```bash
make docs-build       # strict モード — リンク切れ / 設定の問題があれば失敗します
```
