{{プロジェクト名}} 執筆規範
基本情報
| 属性 | 値 |
|---|---|
| 書名 | {{書名}} |
| 対象読者 | {{読者像}} |
| ソースプロジェクト | {{プロジェクト名}} {{バージョン番号}} |
| プログラミング言語 | {{言語}} |
| 推定章数 | {{章数}} |
| 各章の文字数 | {{最低文字数}}〜{{最高文字数}}字 |
| プロジェクトリポジトリ | {{リポジトリURL}} |
文体の定義
- 人称: 一人称複数（「私たち」）
- 口調: {{スタイルの説明}}
- 比喩の密度: 各コア概念につき少なくとも1つの比喩
- ユーモアの程度: {{なし/時々/適度/頻繁}}
- 読者の呼称: {{例：「あなた」/「読者の方」/「開発者の皆さん」}}
文体の例
{{サンプル段落}}
禁止表現
- ❌ {{禁止表現1、例：「言うまでもなく」}}
- ❌ {{禁止表現2、例：「明らかに」}}
- ❌ {{禁止表現3、例：「簡単に言えば」の後に非常に複雑な内容が続く}}
フォーマット規範
見出しのレベル
| レベル | 用途 | 数量制限 | 例 |
|---|---|---|---|
H1 (#) | 章タイトル | 各章1つのみ | # 第3章：ミドルウェアの秘密 |
H2 (##) | 主要節 | 3〜6個/章 | ## リクエストの一生 |
H3 (###) | サブ節 | 必要に応じて | ### ルートマッチングアルゴリズム |
H4 (####) | 使用を避ける | 深すぎる場合は再構成 | — |
コードブロック規範
- 言語の指定は必須:
``` - 重要な行にコメントを追加: 「なぜ」を説明し「何を」ではない
- 1つのコードブロックは30行以内
- 長すぎるコードは省略:
// ...関連のコードを省略...し、省略した内容を説明する - ファイルパスの記載: コードブロックの上にソースファイルパスを記載
段落の管理
- 各段落は 5行以内
- 純粋なテキストを 3段落以上 連続して使わない（コード・図表・リストを挿入する）
- 節の冒頭は ストーリー/問題/サスペンス で始める
- 各H2節の終わりには 次節への橋渡し となる一文を入れる
図表規範
ルール：フロー図、アーキテクチャ図、階層図、ディレクトリツリーが必要な箇所はすべて Mermaid を使用し、ANSI ボックス文字（┌ ─ ┤ ├ └ │）の使用を禁止する。
- フロー図は {{フロー系のシーン、例：リクエスト処理フロー}} の説明に使用
- クラス図は {{構造系のシーン、例：モジュール依存関係}} の説明に使用
- 各図には必ず タイトル と 簡単な説明 を付ける
よく使う図の種類：
| シーン | 図の種類 | 命令 |
|---|---|---|
| 垂直階層アーキテクチャ（分層アーキテクチャ図など） | flowchart | flowchart TD |
| 水平処理フロー | flowchart | flowchart LR |
| 読書ロードマップ / 複数ステップの順序 | flowchart | flowchart TD + --> |
| ファイルディレクトリツリー | graph | graph LR |
| 並列分類の比較 | flowchart | flowchart LR + 分類ノード |
| グループ化/サブシステムレイアウト | flowchart + subgraph | subgraph name["…"] |
構文のポイント：
- スペース・日本語・括弧を含むラベルには引用符が必要：
node["第6層：エントリー (CLI)"] - 複数行ラベルには
<br/>を使用：node["1行目<br/>2行目"]（\nは使えません、Mermaid は認識しません） - ノード ID には英数字のみ使用し、日本語は使わない
**太字**の Markdown 構文はサポートされていないため、プレーンテキストのラベルを使用する
特殊マーカー
- 💡 ヒント: 知識を豊かにする補足情報
- ⚠️ 注意: 陥りやすいワナ
- 🔍 深堀り: スキップ可能な深層の考察
- 📝 演習: ハンズオン実践のすすめ
用語規範
英語のまま保持する用語
{{リスト、例：Promise, callback, middleware, event loop, closure}}
翻訳する用語
| 英語 | 日本語訳 |
|---|---|
| {{英語用語1}} | {{日本語訳1}} |
| {{英語用語2}} | {{日本語訳2}} |
用語使用ルール
- 初出時: 日本語訳（English Original）
- 2回目以降: 日本語訳のみ、または英語のみを使用（上記の約束に従う）
- 見出し内: 日本語を優先し、括弧内に英語を注記
- コードコメント内: コードの言語に従う
センシティブコンテンツの回避
- ❌ 商業製品の優劣を評価しない（例：「XフレームワークはYフレームワークより優れている」）
- ❌ 政治・宗教・ジェンダーのトピックに言及しない
- ❌ 絶対的な表現を避ける（「最良の」「唯一の」「必ず」）
- ✅ 技術比較は客観的に保ち、事実とデータのみを述べる
- ✅ 他者の見解を引用する際は出典を明記する
章の構成テンプレート
# 第{{N}}章: {{章标题}}
## 开场引入（200~300字）
<!-- 用故事/问题/悬念引入。例如：
"想象你正在调试一个线上问题，日志显示请求到达了服务器，
但响应却神秘地消失了。你检查了路由，检查了中间件，
一切看起来都没问题。直到你打开了{{模块}}的源码..."
-->
## {{节标题1}}
<!-- 第一个核心知识点 -->
## {{节标题2}}
<!-- 第二个核心知识点 -->
## {{节标题3}}
<!-- 第三个核心知识点。3~5个H2节为宜 -->
## 代码解析
<!-- 带注释的关键代码段，分步骤讲解 -->
## 设计思考
<!-- 为什么作者这样设计？有什么替代方案？做了什么取舍？ -->
## 小结
<!-- 200字以内，回顾本章要点，用列表形式 -->
## 思考题（可选）
<!-- 2~3个启发性问题，不是考试题，而是引导读者深入思考 -->
1. {{问题1}}
2. {{问题2}}相互参照規範
- 前向き参照: 「第{{N}}章でこのトピックについて詳しく説明します」
- 後向き参照: 「第{{N}}章で述べたように、...」
- 循環参照を避ける（AがBを参照し、BがAを参照する）
バージョンと更新
- ソースプロジェクトの新バージョンがリリースされたとき: {{対応方針、例：「影響を受ける章のみ更新」}}
- 正誤表のプロセス: {{例：「audit-log.md に記録し、次回のレビューで修正」}}