HCPチャートとMakingHCPChartSkill入門

目次

1. HCPチャートとは何か
2. このリポジトリが解決する課題
3. リポジトリ構成を最短で把握する
4. 10分ハンズオン（GCDサンプル）
5. サンプル2例の読み方
6. 中で何をしているか（HCPチャート）
7. まとめ

HCPチャートを「仕様として読める図」にしたいとき、手書きの図だけでは運用が難しくなります。 MakingHCPChartSkill は、HCP-DSL（テキスト）を仕様に沿って解釈し、決定的なSVG（同じ入力からは常に同じSVGが出る、という意味です）を返すためのスキルリポジトリです。

この記事では、HCPチャートの基本から始めて、実際に動かすところまでを一気に確認します。

この記事の知識マップ

HCPチャートは日本電信電話公社の横須賀電気通信研究所で考案された階層的な図法で、MakingHCPChartSkillはこれをテキストで書くためのHCP-DSLと、それを検証・レンダリングするPython製スクリプトhcp_render_svg.pyを提供します。hcp_render_svg.pyは非推奨となった旧スクリプトhcp_xml_to_svg.pyの後継で、標準ライブラリのみに依存するPython 3で動作し、renderAllModulesとmoduleは同時に指定できないという制約を持ちます。HCP-DSLの記述では、最上位に目的ラベルだけを書くという記述粒度の規約が必須ルールとして定められています。OpenAI Codexのようなコーディングエージェントは、このスキルをホームディレクトリ配下のskillsフォルダーへ配置することで呼び出せます。

flowchart LR
    accTitle: HCPチャートとMakingHCPChartSkillの知識マップ
    accDescr: HCPチャートという図法とそれを実装するHCP-DSL・記述粒度の規約の関係、MakingHCPChartSkillがhcp_render_svg.pyでHCP-DSLをSVGへ変換し旧スクリプトhcp_xml_to_svg.pyを置き換えたこと、Codexからの利用形態、renderAllModulesとmoduleパラメータの排他関係を示す図
    hcp_chart["HCPチャート"]
    making_hcp_chart_skill["MakingHCPChartSkill"]
    hcp_dsl["HCP-DSL"]
    hcp_render_svg["hcp_render_svg.py"]
    hcp_xml_to_svg["hcp_xml_to_svg.py"]
    description_granularity_convention["記述粒度の規約"]
    codex["Codex"]
    render_all_modules_option["renderAllModules"]
    module_parameter["moduleパラメータ"]
    python["Python"]
    diagnostics_output["diagnostics(診断結果)"]
    hcp_dsl -->|"実装を担う"| hcp_chart
    hcp_render_svg -->|"実装を担う"| hcp_chart
    making_hcp_chart_skill -->|"利用する"| hcp_dsl
    making_hcp_chart_skill -->|"利用する"| hcp_render_svg
    hcp_render_svg -->|"実装を担う"| hcp_dsl
    hcp_render_svg -->|"の後継"| hcp_xml_to_svg
    hcp_dsl -->|"前提とする"| description_granularity_convention
    making_hcp_chart_skill -->|"前提とする"| description_granularity_convention
    codex -.->|"利用する"| making_hcp_chart_skill
    render_all_modules_option -->|"両立しない"| module_parameter
    hcp_render_svg -->|"利用する"| render_all_modules_option
    hcp_render_svg -->|"利用する"| module_parameter
    hcp_render_svg -->|"前提とする"| python
    hcp_render_svg -->|"実装を担う"| diagnostics_output

図の実線は常に成り立つ関係、破線は条件付きの関係です(成立条件は詳細ページの各関係の説明に記載)。関係すべての一覧(全14件、根拠・確度つき)と主要概念の定義は知識マップ詳細ページにまとめています。データ: JSON-LD / Turtle

1. HCPチャートとは何か

HCPチャートは、処理を階層的に記述するための表現です。 このリポジトリでは、次の書き方が必須ルールとして扱われています。

• 左側は「何を達成するか（目的）」
• 右側（深いインデント）は「どう達成するか（手段・詳細）」
• 最上位（レベル0）には目的ラベルを書く

このルールに沿ってテキストを書くことで、設計意図と実装詳細の対応が読み取りやすくなります。

1.1. HCP の由来と、他の図法との違い

HCP は Hierarchical ComPact description chart の略で、日本電信電話公社（現 NTT）の横須賀電気通信研究所で作られた図法です。つまり、この記事やリポジトリの造語ではなく、以前から日本で使われてきた記法です。特徴としては、処理を階層的に書けること、データと処理の関係を書き添えやすいこと、フリーハンドでも書きやすいこと、そして説明を枠の中ではなく記号の近くに置くため 1 枚に多くの内容が入ることが挙げられます。

他の図法と並べると、位置づけが見えやすくなります。

そのうえで、この記事で扱う MakingHCPChartSkill 固有のものは、記法そのものではなく次の 2 つ です。

• HCPチャートをテキストで書くための HCP-DSL と、その解釈仕様（references/hcpchartspec.md）
• 「レベル 0 には目的ラベルだけを書き、代入や比較のようなコード風の記述は子ノードへ下げる」という 記述粒度の規約。これはリポジトリ側が必須ルールとして定めているもので、HCPチャート一般の決まりではありません

1.2. HCP-DSL の書き方（構文早見表）

書き方の全体像は、次の表でだいたい足ります。詳細な仕様は references/hcpchartspec.md、要点だけなら references/hcp-chart-schema.md にまとまっています。

行の種類

インデント（階層）

コマンド

最小の例は次のようになります。\module から始めて、目的を左に、手段を右に置くだけです。

\module main
入力を受け取り前提を確認する
    値が正の整数であることを確かめる
\fork 入力は妥当か
    \true はい
        本処理を実行する
    \false いいえ
        エラーとして呼び出し元へ返す
        \return
結果を返す

2. このリポジトリが解決する課題

図だけを人手で管理していると、こうした問題が起きがちです。

• 図と仕様テキストがズレる
• 分岐や階層の制約が曖昧になる
• 差分レビューしづらい

MakingHCPChartSkill では、HCP-DSLをJSONリクエストとして渡し、hcp_render_svg.py が検証と描画を行います。 同じ入力なら同じ出力になるため、図をCIやレビューに組み込みやすい構成です。

3. リポジトリ構成を最短で把握する

対象リポジトリ: https://github.com/gomurin0428/MakingHCPChartSkill

• hcp-chart-svg-v2/SKILL.md スキルの使い方と制約（renderAllModules と module の同時指定禁止など）。
• hcp-chart-svg-v2/scripts/hcp_render_svg.py JSON入力を検証し、HCP-DSLを解釈してSVGレスポンスを返す本体。
• hcp-chart-svg-v2/references/ 仕様リファレンス、サンプルrequest/response、サンプルSVG。
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py deprecated。現在は hcp_render_svg.py を使う。

4. 10分ハンズオン（GCDサンプル）

前提環境

4.1. リポジトリを取得する

git clone https://github.com/gomurin0428/MakingHCPChartSkill.git
cd .\MakingHCPChartSkill

4.2. スキルをローカル Codex に配置する

ここでいう Codex は、OpenAI のコーディングエージェントのことです。$HOME\.codex（Windows なら C:\Users\<ユーザー名>\.codex）がその設定ディレクトリで、リポジトリの README では、その下の skills\<スキル名> へディレクトリごとコピーする手順が案内されています。こうしておくと、エージェントに「HCPチャートを描いて」と頼んだときに、この SKILL.md の手順どおりレンダラを呼んでもらえます。

Copy-Item -Recurse -Force .\hcp-chart-svg-v2 "$HOME\.codex\skills\hcp-chart-svg-v2"

この手順は必須ではありません。 レンダラは --input と --output を取る単体のスクリプトなので、Codex を使っていない方は 4.3 へ進んでください。

4.3. サンプル入力からSVGレスポンスを生成する

python .\hcp-chart-svg-v2\scripts\hcp_render_svg.py `
  --input .\hcp-chart-svg-v2\references\example-gcd-request.json `
  --output .\hcp-chart-svg-v2\references\example-gcd-response.json `
  --pretty

4.4. レスポンスJSONからSVGを取り出す

$r = Get-Content -Raw .\hcp-chart-svg-v2\references\example-gcd-response.json | ConvertFrom-Json
$r.svg | Set-Content -NoNewline -Encoding utf8 .\hcp-chart-svg-v2\references\example-gcd.svg

4.5. 補足（入力制約）

• renderAllModules=true のときは module を指定できません。
• diagnostics に error がある場合、svg または svgs は空になります。

5. サンプル2例の読み方

図を開いたとき、次の順で目を動かすと読めます。

1. いちばん左の列だけを上から下へ読む。 ここに並んでいるのが「何を達成するか（目的）」で、処理全体のあらすじになります
2. 気になった行から右へたどる。 右のインデントに並ぶのが、その目的を「どう達成するか（手段・詳細）」です
3. 縦線（幹）で親子を確認する。 幹は同じ深さの処理をつないでいて、深さが浅い行を突き抜けないように描かれます

記号の意味は次のとおりです。

5.1. ユークリッドの互除法（GCD）

• 入力例: example-gcd-request.json
• 出力例: example-gcd-response.json

「入力の受け取り」「繰り返し」「返却」が階層で分離されていて、処理の目的と手段が追いやすい構成です。

左端の列だけを読むと「入力値を受け取り計算の準備をする → 余りが残る間に最大公約数へ近づける → 結果を利用者に返す」の 3 行で、これだけでアルゴリズムのあらすじが分かります。r <- a mod b のような具体的な計算は、繰り返しの内側の「次に引き継ぐ値を決める」から、さらに右のインデントへ下げられています。この位置関係が「目的（左）と手段（右）」の対応そのもの です。左端にいきなり r <- a mod b が出てきたら、記述粒度の規約（1.1）に反している合図になります。

図の上部にある Data: の行と、ノードの下に付く in: / out: の注釈も読み方の手がかりです。この図では in: a, b と out: a が付いていて、どこが入口でどこが出口かが図だけで分かります。

5.2. 受注承認フロー

• 入力例: example-order-approval-request.json
• 出力例: example-order-approval-response.json

業務フローでも、fork と true/false を使って分岐の意図を明確に記述できます。

こちらも左端の列は「受注内容を受け付ける → 出荷可否を判定する → 処理結果を返す」の 3 行だけです。在庫照会、承認申請、出荷登録といった実装寄りの操作は、すべて右のインデントへ入っています。分岐は幹から右へ出る矢印で、(はい) / (いいえ) の下にそれぞれの処理がぶら下がる形です。「欠品なら差し戻し、承認済みなら出荷手配、そうでなければ保留」という業務判断が、2 か所の分岐から出る矢印をたどるだけで追えます。

業務仕様のレビューでは、この左端の列を関係者と読み合わせ、右側の詳細は実装担当と詰める、という分担がしやすくなります。

6. 中で何をしているか（HCPチャート）

execute_request の処理フローを、HCP-DSLで書くとこうなります。

\module main
リクエストを受け取り前提を確認する
    入力JSONの必須項目を検証する
DSLを解析して構造化する
    モジュールと階層を解釈する
    diagnostics を収集する
診断結果に応じて応答経路を選ぶ
    \fork error が存在するか
        \true はい
            空の SVG 系ペイロードを返す
        \false いいえ
            描画対象モジュールを決定する
            \fork renderAllModules が true か
                \true はい
                    全モジュールの SVG を生成する
                    svgs を含む応答JSONを組み立てる
                \false いいえ
                    単一モジュールの SVG を生成する
                    svg を含む応答JSONを組み立てる
結果を呼び出し元へ返す

上のDSLを実際にレンダリングした図がこちらです。

7. まとめ

HCPチャートは、図として見やすいだけでなく、仕様として扱える形で管理できるのが強みです。 MakingHCPChartSkill を使うと、HCP-DSLを検証しながらSVGまで一貫して生成できます。

次に試すなら、普段の処理仕様を1つHCP-DSLで書き、diagnostics を見ながら整形していくと導入効果が実感しやすいです。

参考資料

• MakingHCPChartSkill
• hcp-chart-svg-v2/SKILL.md
• hcp-chart-svg-v2/scripts/hcp_render_svg.py
• hcp-chart-svg-v2/references/hcpchartspec.md（DSL の完全な仕様）
• hcp-chart-svg-v2/references/hcp-chart-schema.md（構文の要点）
• HCPチャート - Wikipedia（正式名称と由来）

関連する記事

同じタグを共有する最新の記事です。さらに近い話題で知識を深められます。

関連トピック

このテーマと近いトピックページです。記事を起点に、関連するサービスや他の記事へ進めます。

このテーマがつながるサービス

この記事は次のサービスページにつながります。近い入口からご覧ください。

よくある質問

この記事のテーマについて、相談時によくある質問をまとめています。

HCPチャートとは何ですか？

処理を階層的に記述するための表現です。左側に「何を達成するか（目的）」を書き、右側の深いインデントに「どう達成するか（手段・詳細）」を書き、最上位（レベル0）には目的ラベルを書きます。このルールに沿ってテキストを書くことで、設計意図と実装詳細の対応が読み取りやすくなります。

MakingHCPChartSkillは何をするツールですか？

HCP-DSL（テキスト）を仕様に沿って解釈し、決定的なSVGを返すためのスキルリポジトリです。HCP-DSLをJSONリクエストとして渡すと、hcp_render_svg.pyが検証と描画を行います。同じ入力なら同じ出力になるため、図をCIやレビューに組み込みやすい構成です。

図を手書きで管理する場合と何が違いますか？

図だけを人手で管理していると、図と仕様テキストがズレる、分岐や階層の制約が曖昧になる、差分レビューしづらいという問題が起きがちです。HCP-DSLというテキストから決定的にSVGを生成する方式なら、図を仕様として扱える形で管理でき、diagnosticsを見ながら整形していけます。

使ううえでの制約はありますか？

renderAllModules=trueのときはmoduleを同時指定できません。また、diagnosticsにerrorがある場合、svgまたはsvgsは空になります。スクリプトはhcp_xml_to_svg.pyがdeprecatedとなっており、現在はhcp_render_svg.pyを使います。

著者プロフィール

記事の著者プロフィールページです。

小村 豪

合同会社小村ソフト 代表

Windows ソフト開発、技術相談、不具合調査を中心に、既存資産が残る案件や原因が見えにくい障害調査に強みがあります。