openapi-mcp: Instructions file for GitHub Copilot

日本語文書作成・品質基準指針

このインストラクションは、読みやすく統一された日本語文書を作成するための指針を提供します。

コーディング規約

基本原則

• 技術文書として明確で読みやすい日本語表現を使用する
• プロジェクト固有の用語統一ルールに従う
• 文体・スペーシング・表記を一貫させる

文体・表現ルール

敬体・常体の統一

基本的に「ですます調」で統一しますが、リスト項目は内容に応じて以下のように使い分けます。

リスト項目の文体ルール

体言止めを使用する場合:

名詞的な列挙(項目、対象、範囲、特徴、メリット等)は体言止めで記述します。

• 例(対象範囲の列挙):
  • プロジェクトの目的
  • 使用技術スタック
  • 開発体制
• 例(特徴の列挙):
  • 高速な処理性能
  • 柔軟な拡張性
  • 直感的なUI

「〜します」形式を使用する場合:

動作や手順の説明は「〜します」で記述します。

• 例(動作説明):
  • ファイルを作成します
  • 設定を確認します
  • サーバーを起動します

「〜してください」形式を使用する場合:

読者への指示や依頼は「〜してください」で記述します。

• 例(指示):
  • 以下のコマンドを実行してください
  • エラーログを確認してください
  • 設定ファイルを編集してください

重要: 同一リスト内では文体を統一し、体言止めと動詞形式を混在させないこと

技術文書向け表現

• 一文の長さ: 100文字以内を目安
• 改行の使用: 可読性向上のため、適切に改行を入れる
  • 句点(。)の後: 基本的に改行を入れる
  • 読点(、)の後: 一文が長い場合(60文字超)や、複数の情報が含まれる場合は改行を検討
  • 複数の概念や事実を説明する場合: 箇条書きの活用を優先
  • NG: 「これは説明です。次の説明です。さらに説明です。」(改行なし)
  • OK: 「これは説明です。」「次の説明です。」「さらに説明です。」(改行あり)
  • Better: 箇条書きで構造化
• 二重否定: 使用を避け、肯定的表現を優先
  • NG: 「有効化しないわけではありません」
  • OK: 「有効化します」または「有効化できます」
• 冗長表現: 簡潔で明確な表現を使用
  • NG: 「することができます」→ OK: 「できます」
  • NG: 「という形で」→ OK: 「として」または削除
• 弱い表現: 断定的で明確な表現を優先
  • NG: 「〜かもしれません」→ OK: 「〜の可能性があります」
  • NG: 「〜だと思います」→ OK: 「〜です」または「〜と考えられます」

禁止される表現

• 解説調表現: 「〜について説明します」「見ていきましょう」
• ブログ調表現: 「いかがでしたか」「まとめると」
• 不必要な感嘆符: 技術文書では感嘆符の使用は最小限に

記号・文字種ルール(厳守)

以下のルールは必ず適用すること。コード生成時・ドキュメント作成時に自動チェックを実施すること。

数字

• 全角数字は使用禁止、必ず半角数字を使用
• チェック方法: [０-９]が含まれていないか確認
• 例: NG「１２３」→ OK「123」

括弧・記号

• 全角括弧（）と全角記号＜＞：／＋－＊＝は使用禁止、必ず半角表記を使用
• 適用対象
  • 技術用語・ファイル名・設定値の補足説明(括弧)
  • コード内の括弧表現
  • URL・リンク内の括弧
  • 山括弧: タグ表記(例: <HTML>)、不等号(例: x < 10)
  • コロン: リスト項目の説明(例: * 項目名: 説明)、キー・バリューペア(例: key: value)
  • スラッシュ: 選択肢の区切り(例: 入れる/入れない、有償 / 無償)、パス表記(例: /usr/local/bin)
  • 演算子: 数式表記(例: 1+2-3*4)、リスト記号(例: - 項目、* 項目)、代入式(例: x = 10)
• チェック方法: （|）|＜|＞|：|／|＋|－|＊|＝が含まれていないか確認
• 例:
  • NG「設定ファイル（config.yml）」→ OK「設定ファイル(config.yml)」
  • NG「＜HTML＞」→ OK「」
  • NG「項目名：説明」→ OK「項目名: 説明」
  • NG「有償／無償」→ OK「有償/無償」または「有償 / 無償」
  • NG「データ取得＋加工＋送信」→ OK「データ取得+加工+送信」
  • NG「x＝10」→ OK「x = 10」