> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/styleguide/build-your-style-guide.md).

# スタイルガイドを作成する

開始点を選び、テンプレートに入力し、GitBook Agent が適用できるルールを書きます。

ほとんどのチームはテンプレートから始め、スタイルガイドを1ページにまとめています。このページでは、出発点の選び方、テンプレートの記入方法、そして GitBook Agent が適用できるルールの書き方を説明します。

このサイトでスタイルガイドを設定するには、管理者権限が必要です。

## 出発点を選ぶ

まず、クリックします **スタイルガイド** サイトのサイドバーで、次にクリックします **設定**。次に、開始方法を選択します。

| 開始点            | 次のときにこれを選びます                                                                                       |
| -------------- | -------------------------------------------------------------------------------------------------- |
| **テンプレート**     | まだスタイルガイドがありません。                                                                                   |
| **既存のスタイルガイド** | 組織内の別のサイトで、使いたいスタイルガイドがすでに使用されています。詳しくは、次をご覧ください。 [既存のスタイルガイドを使用する](#use-an-existing-style-guide). |
| **インポート**      | 別のツールでスタイルガイドを管理しているか、オンラインで公開しています。詳しくは、次をご覧ください。 [スタイルガイドをインポートする](#import-a-style-guide).       |

GitBook には3つのテンプレートがあります：

<table><thead><tr><th width="204.75390625">テンプレート</th><th>おすすめ</th></tr></thead><tbody><tr><td><strong>スターターテンプレート</strong></td><td>自分たちのトーンとルールをゼロから定義します。各セクションには何を入れるべきかが説明され、ルールは自分で書きます。</td></tr><tr><td><strong>Google スタイルガイド</strong></td><td>開発者向けの、明確で正確かつプロフェッショナルな文章。Google の開発者向けドキュメントのスタイルガイドをもとに生成されています。</td></tr><tr><td><strong>Microsoft スタイルガイド</strong></td><td>幅広い読者向けの、温かく、シンプルで、人間味のある文章です。技術の専門家でない読者も含みます。Microsoft Writing Style Guide をもとに生成されています。</td></tr></tbody></table>

Google と Microsoft のテンプレートには、元のガイドに基づく適用可能なルールが含まれており、トーン、単語リスト、文法、書式、手順、アクセシブルな文章、インクルーシブな言語をカバーします。テンプレート内のすべては編集できます。

{% hint style="info" %}
GitBook は、元のガイドが変更されるとテンプレートを更新します。更新は新しいスタイルガイドにのみ適用されます。すでに作成済みのスタイルガイドは変更されません。
{% endhint %}

## テンプレートを記入する

各テンプレートは1ページ構成で、トーンと文体、単語リスト、文法、書式、手順などのセクションに分かれています。各セクションには、何を入れるべきかが説明されています。不要なセクションは削除してください。

どのテンプレートでも、カスタマイズが必要な箇所には **入力が必要** というヒントが付いています。最初のチェックを実行する前に、すべての項目を確認してください。通常、次のような項目が含まれます。

* テンプレートが反映しているベースガイドの版のスナップショット日付（Google と Microsoft のテンプレート）
* 製品名とドキュメントのミッション
* ドキュメントを読む人・書く人、およびガイドが対象とする範囲
* 製品名、機能名、そしてチームで議論が分かれる用語をワードリストに追加したもの
* オーナー、レビュー頻度、変更提案の方法
* 意思決定ログの最初の記録。チームがあるルールに決めた理由や、ベースガイドから外れた理由を記録します。

ヒントのないものは、そのまま使えます。まだプレースホルダーテキストが入っているルールは、記入するまで無効です。

## Agent が適用できるルールを書く

GitBook Agentは、番号付きIDがあるルールや、「セミコロンは絶対に使わない」のような明確なルールを適用します。それ以外のもの（文体の説明など）はガイダンスとして扱い、提案としてのみ提示します。詳しくは、次をご覧ください。 [GitBook Agentによるスタイルガイドの適用方法](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/styleguide/how-gitbook-agent-enforces-your-style-guide.md#which-rules-the-agent-enforces).

テンプレートでは、ルールを表形式で記述します。ID、ルール、良い例と悪い例、例外を含みます：

| ID    | ルール    | 良い例                    | 悪い例                       | 例外                                     |
| ----- | ------ | ---------------------- | ------------------------- | -------------------------------------- |
| SG-12 | 現在形を使う | ✅ 「そのコマンドはファイルを作成します。」 | ❌ 「そのコマンドはファイルを作成するでしょう。」 | 実際に未来の出来事には未来形を使う（「v2 のサポートは3月に終了します」） |

ルールを作成または編集するときは：

* **適用したいルールにはすべてIDを付けます。** ルールの場所にかかわらず、現在の最大番号の次の番号を使います。過去の指摘や判断ログがIDを参照しているため、IDの振り直しや再利用はしないでください。
* **1つのIDにつき、ルールは1つにします。** 1つのことだけをチェックするルールにすれば、対応しやすい指摘が生成されます。
* **例外を記載します。** ルールの例外に該当するテキストは、Agentによる指摘の対象になりません。
* **チェック可能なガイダンスはルールにします。** 文体の説明はガイダンスとして残し、「本文では感嘆符を使わない」のようにチェック可能な内容は、番号付きのルールとして記述します。
* **すべてのプレースホルダーを置き換えます。** たとえば、 `[Product name]`のような角括弧で囲まれたテキストが残っているルールは、適用されません。

{% hint style="info" %}
Starterテンプレートでは、IDの接頭辞に `SG-` を使用します。変更することもできますが、ガイドの使用を開始した後は同じ接頭辞を使い続けてください。
{% endhint %}

## 主要なルールは最初のページにまとめる

ほとんどのスタイルガイドには1ページで十分です。GitBook Agent は、各タスクで最初のページを読み込むため、そこにあるルールは常に適用されます。

スタイルガイドが長くなったら、長い単語リストやコンテンツタイプなど、1つのトピックに関する詳細ルールは、わかりやすいタイトルの別ページに移してください。Agent は、そのトピックに関するタスクが発生するたびにそのページを読みます。中核となるルールは最初のページに残してください。

## 既存のスタイルガイドを使用する

組織ですでに他のサイトでスタイルガイドを使っている場合は、設定画面の上部に、それを使っているサイトと一緒に表示されます。1つを選ぶと、次のことができます：

* **そのまま使用する：** そのスタイルガイドを使用する他のサイトと共有します。編集内容は、使用されているすべての場所に反映されます。
* **フォークする：** このサイト用のコピーを作成します。名前は `Style guide - {site name}`となり、元のガイドとは独立して変更できます。

## スタイルガイドをインポートする

別のツールで管理しているスタイルガイドをインポートするには：

1. 設定画面で、クリックします **ファイルをアップロード**.
2. Markdown、HTML、DOCX、ZIP ファイルをドロップするか、参照して選択してください。
3. 必要に応じて、 **AIでインポートを強化** を有効にして、インポートしたコンテンツを整えます。
4. 「 **インポートを開始**.

オンラインで公開されているスタイルガイドをインポートするには：

1. 設定画面で、クリックします **URLからインポート**.
2. スタイルガイドへのリンクを入力します。
3. 必要に応じて、 **AIでインポートを強化** を有効にして、インポートしたコンテンツを整えます。

GitBookは、入力したURL配下にある公開ページを最大200件インポートします。たとえば、 `website.com/docs/` をインポートすると、 `website.com/docs/article` は含まれますが、 `website.com/other-parent/page`は含まれません。大規模なサイトでは、より小さなサブパスに分けてインポートしてください。

インポートしたスタイルガイドは、複数ページにまたがり、ID のないルールが含まれていることがよくあります。最初のチェックを実行する前に：

1. 中核となるルールを最初のページに移します。
2. 適用したいルールには、それぞれ ID を付け、ガイド全体で1つの接頭辞を使います。
3. 他のガイドから参照しているルールは書き出してください。Agent は、スタイルガイドに書かれている内容だけを適用します。

## 最初のチェックの前に

スタイルガイドの準備が整うのは次のときです：

* すべての **入力が必要です** セクションが入力され、ルールにプレースホルダーのテキストが残っていないことを確認します。
* 製品名と確定した用語が単語リストに入っていること。
* 適用したいルールにすべて ID が付いていること。
* 中核となるルールが最初のページにあること。

次に、 [スタイルガイドに照らしてコンテンツを確認します](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/styleguide/check-content-against-your-style-guide.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/styleguide/build-your-style-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
