kidoc

kidoc — エンジニアリング文書化スキル

KiCad プロジェクトファイルから、プロフェッショナルなエンジニアリング文書を生成します。

クイックスタート

1 つのコマンドですべてのひな形を生成できます。解析、図、レンダリング結果、Markdown がすべて自動的に作成されます。

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir /path/to/kicad/project \
  --type hdd \
  --output reports/HDD.md

.kicad_sch ファイルと .kicad_pcb ファイルを自動検出し、回路図／PCB／EMC／熱解析を実行して、ブロック図と回路図の SVG レンダリング結果を生成します。さらに、事前入力済みのデータ表と説明文のプレースホルダーを含む、構成済みの Markdown ひな形を作成します。

PDF を生成するには：

python3 skills/kidoc/scripts/kidoc_generate.py \
  --project-dir /path/to/kicad/project \
  --doc reports/HDD.md \
  --format pdf

初回実行時に reports/.venv/ を自動作成します（PDF／DOCX／ODT のみ。HTML は依存関係なしで使用できます）。

ワークフロー

1. ひな形を生成 — kidoc_scaffold.py が利用可能な解析をすべて自動実行し、回路図をレンダリングして図を生成し、Markdown のひな形を書き出します。
2. 説明文を記入 — エージェントがひな形を読み込み、各 `` プレースホルダーにエンジニアリング文書を記入します。エンジニアがレビューして編集します。
3. 再生成 — 再実行すると、`` マーカーで囲まれたデータセクションが新しい解析結果に更新されます。ユーザーが記述した説明文の内容は保持されます。
4. 出力をレンダリング — kidoc_generate.py が PDF、HTML、DOCX、または ODT を生成します。

ドキュメントの種類

種類	名前	主なセクション
hdd	ハードウェア設計記述書	システム概要、電源、信号、アナログ、熱、EMC、PCB、機構、BOM、テスト、適合性
ce_technical_file	CE 技術文書	製品 ID、必須要件、整合規格、リスク評価、適合宣言
design_review	設計レビュー資料	レビュー概要（複数解析のスコア）、指摘事項、アクション項目
icd	インターフェース管理文書	インターフェース一覧、コネクターごとのピン配置の詳細、電気的特性
manufacturing	製造移管資料	組み立て概要、PCB 製造上の注意事項、組み立て手順、テスト手順
schematic_review	回路図レビュー報告書	システム概要、電源、信号、アナログ、BOM、回路図付録
power_analysis	電源解析レポート	電源設計、熱、EMC、BOM
emc_report	EMC 事前適合性レポート	EMC 解析、適合性、回路図付録

カスタムレポート

--spec を使うと、任意のセクション順でレポートを生成できます。

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir . --spec my-report.json --output reports/custom.md

仕様の形式（JSON）：

{
  "type": "custom",
  "title": "USB Interface Analysis",
  "sections": [
    {"id": "front_matter", "type": "front_matter"},
    {"id": "signal_interfaces", "type": "signal_interfaces"},
    {"id": "bom", "type": "bom_summary"}
  ]
}

各セクションの type は、既知のセクション種別（上記のドキュメントの種類の表で使用している名前と同じ）と一致する必要があります。id フィールドは、そのセクションのインスタンスを識別する一意のキーです。

組み込みの各種類のデフォルト仕様全体を確認するには：

python3 skills/kidoc/scripts/kidoc_spec.py --expand hdd
python3 skills/kidoc/scripts/kidoc_spec.py --list

--spec フラグは kidoc_generate.py でも使用できます（プロジェクト名のフォールバックとして仕様のタイトルを使用します）。

回路図とPCBのレンダリング

レンダリングは図の生成エンジンに統合されています。オーケストレーターとスキャフォールドは、ドキュメント生成の一環として回路図とPCBビューを自動的にレンダリングします。

# Generate all figures (diagrams + schematic/PCB renders) from analysis JSON
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --output reports/figures/

# Full orchestration with spec, analysis, and project files
python3 skills/kidoc/scripts/kidoc_orchestrator.py --analysis schematic.json \
    --project-dir . --output reports/figures/

図のジェネレーターは、全シートのレンダリング（ルートシートとすべてのサブシート）、サブシステムの切り抜き（仕様の各セクションにおける focus_refs）、ネットのハイライト表示、ピンレベルのネット注釈、およびすべてのPCBレイヤープリセットに対応しています。これらのオプションは、ドキュメント仕様で設定するか、分析辞書を介して渡します。

ジェネレーターフレームワークから利用できるレンダリング機能：

• 切り抜き：特定のコンポーネント参照番号を囲むサブシステムのバウンディングボックスに焦点を当てます
• フォーカス／減光：フォーカス対象のコンポーネントを不透明度100％で表示し、その他を15％まで減光します
• ネットのハイライト表示：BFSを使用して特定のネットを色分け表示します
• ピンネット：ピンの先端にピンレベルのネット名を注釈表示します

プログラムから直接利用するには、figures.renderers を使用します。

from figures.renderers import render_schematic, render_pcb
render_schematic('design.kicad_sch', 'output/', crop_refs=['R1', 'R2'], highlight_nets=['VCC'])
render_pcb('board.kicad_pcb', 'output/', preset_name='assembly-front')

レイヤープリセット：

プリセット	表示内容
assembly-front	表面のシルク、製造図、パッド、外形
assembly-back	裏面のシルク、製造図、パッド、外形（反転）
routing-front	表面の銅箔、パッド、ビア、外形
routing-back	裏面の銅箔、パッド、ビア、外形
routing-all	すべての銅箔レイヤー、パッド、ビア、ゾーン
power	電源プレーン、ビア、ゾーンの外形

追加オプション：--highlight-nets、--crop-refs、--crop x,y,w,h、--mirror、--overlay annotations.json（引き出し線付きのコールアウトボックス）。

ブロック図

python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --all --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --power-tree --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --bus-topology --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --architecture --output diagrams/

回路図の分析JSONから生成されます。電源ツリーには、インダクターの値、コンデンサーの概要、および出力電圧とともに、レギュレーターのトポロジーが表示されます。

出力形式

形式	SVGの扱い	依存関係
Markdown	画像参照	依存関係なし
HTML	ベクターとしてインライン化	依存関係なし
PDF	svglibによるベクター変換、カスタムコンバーターへのフォールバック、ラスターへのフォールバック	仮想環境（reports/.venv/）
DOCX	300 DPIのPNGにラスタライズ	仮想環境
ODT	300 DPIのPNGにラスタライズ	仮想環境

PDF出力には、スタイル付きの表紙、目次、行を交互に色分けした書式付きテーブル、およびベクターSVG図が含まれます。

設定

レポート設定は、.kicad-happy.json の "reports" キーの下に記述します。設定ファイルは階層的に適用されます。~/.kicad-happy.json（ユーザーレベルのデフォルト設定。会社のブランディングなど）は、プロジェクトレベルの設定とマージされます。

{
  "project": {
    "name": "Widget Board",
    "number": "HW-2024-042",
    "revision": "1.2",
    "company": "Acme Electronics",
    "author": "Jane Smith",
    "market": "eu"
  },
  "reports": {
    "classification": "Company Confidential",
    "documents": [
      {"type": "hdd", "output": "HDD-{project}-{rev}", "formats": ["pdf", "docx"]}
    ],
    "branding": {
      "logo": "templates/logo.png",
      "header_left": "{company}",
      "header_right": "{number} Rev {rev}"
    }
  }
}

説明文の作成

スキャフォールドを生成した後、説明文用のプレースホルダーセクションにエンジニアリングに関する文章を記入します。

ワークフロー

1. コンテキストビルダーを実行し、各セクションに必要なデータを取得します。

   python3 skills/kidoc/scripts/kidoc_narrative.py \
     --analysis analysis/schematic.json \
     --section power_design
   

   または、すべての説明文セクションのコンテキストをまとめて作成します。

   python3 skills/kidoc/scripts/kidoc_narrative.py \
     --analysis analysis/schematic.json \
     --report reports/HDD.md
   

2. 各セクションについて、コンテキストを読み、次の点を踏まえて文章を作成します。

   • 何かだけでなくなぜかを説明します。設計上の根拠やトレードオフを記述します
   • 具体的なコンポーネント値と部品番号を挙げます
   • 定量的な表現を使います（「十分な静電容量」ではなく「2.3msのホールドアップ時間」）
   • データシートの推奨事項からの逸脱を明記します
   • 利用可能な場合は、SPICE検証の結果を参照します

3. Markdown内のイタリック体のプレースホルダー *[...]* を実際の文章に置き換えます。

4. 再生成時には、データテーブルが自動的に更新されます。データに変更があった場合は、説明文との整合性を確認します。

スタイルガイド

上級EEが同僚に説明するように記述します。

• 重要な発見または決定事項から始めます
• 分析で得られた具体的な数値を根拠として示します
• リスクや逸脱事項を記します
• 段落は3～5文にまとめます
• テーブルにすでに記載されているデータを繰り返しません

要件

• Python 3.9以降とpython3-venv（PDF／DOCX／ODTの生成用）
• KiCadの回路図ファイル（.kicad_sch、KiCad 6以降）（SVGレンダリング用）
• **任意：**分析JSONは.kicad_sch／.kicad_pcbから自動生成されます。analysis/内（または.kicad-happy.jsonで設定されたパス内）に事前生成済みのJSONがある場合は、それが使用されます。生成された図（ダイアグラム、回路図SVG）は、Gitで追跡できるようreports/figures/に配置されます

制限事項

• 回路図および PCB レンダラーは KiCad 6 以降のフォーマット（.kicad_sch、.kicad_pcb）のみをサポートします
• ナラティブセクションにはエージェントまたは手動での執筆が必要です — スキャフォールドは構造とデータを提供しますが、文章は提供しません
• SPICE シミュレーション結果には手動でのシミュレーション設定が必要です（スキャフォールドによる自動実行は行われません）
• PDF ベクター SVG の埋め込みは、利用可能な場合は svglib を使用します。svglib が特定の SVG を解析できない場合はラスターにフォールバックします

関連スキル

スキル	関係
kicad	スキャフォールドが消費する回路図/PCB/熱解析 JSON を生成します
emc	EMC セクション用の EMC 解析 JSON を生成します
spice	SPICE シミュレーション結果はアナログ設計セクションに表示されます
bom	BOM データは BOM サマリーセクションに表示されます

まず kicad スキルのアナライザーを実行し、次に利用可能であれば emc と spice を実行してください。スキャフォールドはソースファイルが存在する場合、kicad と emc の解析を自動実行するため、手動での事前解析は SPICE の場合にのみ必要です。