| name | cto-briefing |
| description | CTO 向けのアルゴリズム・設計思想の概要資料を **単一の HTML ファイル** として作成する。技術的な実装詳細ではなく、大枠のロジック・判断基準・設計意図を簡潔にまとめ、ブラウザでそのまま開けるリッチな資料として渡す。プロジェクトのアルゴリズムや設計を俯瞰的に説明する資料が求められた時に使用する。 |
| user-invocable | true |
CTO 向けアルゴリズム概要資料 (HTML) の作成ガイド
CTO やステークホルダーが短時間で全体像を把握できる、アルゴリズム・設計思想の概要資料を 単一の HTML ファイル として作成する。
参考: Thariq Shihipar "Using Claude Code: The Unreasonable Effectiveness of HTML" (Anthropic, 2026-05-08)
なぜ HTML か (Markdown を使わない理由)
CTO 向け資料は 「最後まで読まれること」が最重要。Markdown は 100 行を超えるとスキャンされ、判断が形骸化する。HTML は次の点で上回る。
- 長くても読める: タブ・サイドナビ・折りたたみで構造化できる
- 図と表が並べられる: SVG パイプライン図 / 比較表 / 具体例テーブルが 1 ページに同居する
- 共有が簡単: ブラウザに渡すだけ。OS や閲覧アプリを問わず開ける
- 印刷もできる:
@media print を仕込めば PDF 出力もそのまま使える
- engagement が上がる: 同じ内容でも HTML のほうが実際に最後まで読まれる
トークン代は数倍に増えるが、CTO 1 人の 15 分を確保する価値のほうが大きい。
対象読者
- CTO / テックリード / 投資家 / 事業責任者
- コードは読まないが、ロジックの妥当性や設計方針を判断する人
- 10-15 分で読み切れることを前提とする
出力ファイルの絶対ルール (Thariq の単一ファイル原則)
「受け取った人がファイルをダブルクリックしたら、ネット接続なしで完璧に開ける」状態を必ず守る。
| 項目 | ルール |
|---|
| CSS | <head> 内の <style> にインライン。外部 stylesheet / CDN を link しない |
| JavaScript | <script> にインライン。unpkg / jsDelivr 等からの import は しない (基本は JS 不要) |
| 画像 | インライン SVG または base64 で src に埋める。リモート URL は 使わない |
| フォント | system-ui, -apple-system, "Hiragino Sans", "Noto Sans JP", sans-serif。Google Fonts は 使わない |
| 通信 | 実行時に通信が走ってはいけない。オフライン・エアギャップで動くこと |
| フレームワーク | Tailwind / Bootstrap / React 等は使わない。プレーン CSS で書く |
| 出力 | 1 ファイルのみ。.html を 1 つだけ生成し、関連アセットを分けない |
理由: 受信側のネット環境・社内プロキシ・CDN の rot・バージョン破壊に晒されない。10 年後にも同じに開ける。
推奨ページ構造
- ヘッダー: プロジェクト名 / サブタイトル / 更新日 / バージョンバッジ
- 左サイドバーの TOC (デスクトップ時のみ、
position: sticky): 各セクションへの内部リンク
- 本文 (記事の意味的な順序):
- 一言で言うと (リード)
- 全体の流れ (SVG パイプライン図)
- 各ステップの詳細 (見出し + 「設計の意図」 callout)
- 段階的な拡張計画 (任意 / フェーズ表)
- セキュリティ・リスク (任意)
スターターは同ディレクトリの template.html。これをコピーして本文を差し替える。
内容構成
1. 一言で言うと
システムの目的を 技術用語なしで 1-2 文。「何を入力して、何が出力され、ユーザーにどんな価値があるか」。
ページ上は 大きめの段落 (約 1.2rem) + 左 4px アクセントボーダー の "リード" ブロックとして表示する。
例:
ユーザーが Komga (漫画) と Immich (画像) で示した好みを自動学習し、外部サイトの新着から好みに合うコンテンツを選別して自動インポートする。
2. 全体の流れ
パイプライン全体を SVG 図 と 番号付き一行リスト の両方で示す。
- SVG はインライン。
viewBox でスケールさせ、幅は 100%。
- 入力ソース → 処理ブロック → 出力先の関係を矩形と矢印で示す。
- 色は CSS 変数 (
--accent, --muted) から取り、currentColor ベースにする (ダークモード追随)。
<svg role="img" aria-label="..."> + <title> を必ず付ける。
一行の流れ (番号付きで左から右):
1. 嗜好を学ぶ → 2. 削除を検知 → 3. 新着を採点 → 4. 厳選する → 5. 取得・配置
3. 各ステップの詳細
ステップごとに <section id="step-N"> を作る。
<section id="step-1" class="step" aria-labelledby="step-1-h">
<h2 id="step-1-h">1. 嗜好を学ぶ <small>(profile_builder)</small></h2>
<p>1行の概要説明。</p>
<h3>コアメトリクス</h3>
<p>数式または疑似コードで判断基準を示す。実装コードは書かない。</p>
<aside class="intent">
<strong>設計の意図:</strong>
なぜこの方式を選んだか、何を優先したかを 2-3 文で。
</aside>
</section>
「設計の意図」 callout
各ステップの末尾に <aside class="intent"> を必ず置く。これが資料の 核。
スタイル: 淡い背景色 + 左 4px ボーダー。色だけでなく strong ラベルでも判別可能にする (色覚アクセシビリティ)。
良い設計の意図:
- 「ユーザーに追加の操作負担をかけない」(UX)
- 「ロジックの透明性と説明可能性を確保」(保守)
- 「量より質。レビュー負荷を最小化」(運用)
- 「削除という自然な行動を学習に利用」(データ活用)
悪い例:
- 「SQLite を使用しているため」(実装詳細)
- 「パフォーマンスのため」(曖昧)
4. 表の活用
パラメータ・ルール・比較・具体例は <table> で示す。文章より圧倒的に早く読める。
border-collapse: collapse- ヘッダー行に薄いグレー背景
- セル余白は左右 12px / 上下 8px
- 数値列は
class="num" で右寄せ + font-variant-numeric: tabular-nums
- ヘッダーセルは
<th scope="col"> / 行ヘッダーは <th scope="row">
具体例の表 は抽象式より理解を助ける:
| 作者 | RL 作品 | 全作品 | hit_rate | 最終スコア |
|---|
| A | 4 | 4 | 1.0 | 1.5 |
| B | 1 | 4 | 0.25 | 0.25 |
5. 段階的な拡張計画 (任意)
<table> でフェーズ表。現在のフェーズの行に class="current" を当てて強調する (背景色 + 太字)。
6. セキュリティ・リスク (任意)
<ul> で箇条書き。「何を守っているか」を 1 行ずつ。実装手段は書かない。
ビジュアル設計トークン
:root に CSS 変数で集約。prefers-color-scheme でダーク/ライト両対応。
:root {
--bg: #ffffff;
--fg: #0f172a;
--muted: #64748b;
--border: #e2e8f0;
--accent: #2563eb;
--accent-soft: #eff6ff;
--intent-bg: #fff7ed;
--intent-border: #f59e0b;
--code-bg: #f8fafc;
}
最低限のコントラスト: 本文 4.5:1 / 大文字 3:1 (WCAG 2.2 AA)。
印刷対応 (PDF 化)
@media print {
body { font-size: 11pt; color: #000; background: #fff; }
.layout { display: block; padding: 0; max-width: none; }
nav.toc { display: none; }
section { page-break-inside: avoid; }
a { color: inherit; text-decoration: none; }
a[href^="http"]::after { content: " (" attr(href) ")"; font-size: 0.85em; }
}
検証: Chrome の Ctrl+P で A4 / Letter どちらでも崩れないこと。
アクセシビリティ (WCAG 2.2 AA)
<html lang="ja">- 見出しレベルを飛ばさない (
h1 → h2 → h3)
- 図には代替テキスト (
<svg role="img" aria-label="..."> + <title>)
- リンクは下線または明確な色差で識別可能
- フォーカスリングを残す (
:focus-visible { outline: 2px solid var(--accent); })
- 色だけで意味を伝えない (バッジは文字 + 色)
- ランドマーク:
<header>, <nav>, <main> を使う
原則
書くこと
- Why (なぜ): 各設計判断の理由
- What (何を): 各ステップが何をするか
- 数式・具体例: 判断基準を数値で
- トレードオフ: 何を優先し、何を犠牲にしたか
書かないこと
- How (どうやって): コードの実装、クラス名、関数名
- API エンドポイント: REST 仕様
- 設定キー:
.env の変数、config キー
- インフラ構成: サーバー IP、コンテナ ID、デプロイ手順
- ライブラリ名: httpx, pydantic, FastAPI 等の技術スタック
文体
- 日本語、社内資料として自然な文体
- 断定調 (「〜している」「〜する」、「〜と思われる」は避ける)
- 短文 (1 文 40 文字以内が目安)
- 見出しは動詞 (「嗜好を学ぶ」、「嗜好プロファイル構築」ではない)
作成手順
- コードを読む: 主要なパイプライン / エントリポイントからたどる
- ステップを列挙: パイプラインの各段階を特定する
- コアメトリクスを抽出: 数式・閾値・判断基準を取り出す
- 設計意図を言語化: 各ステップごとに「なぜそうしたか」を書く
- 具体例の数値を作る: 抽象式より具体テーブル
- 実装詳細を削る: コード由来の語彙 (クラス名、関数名) を除去
- HTML を組む:
template.html をコピーして本文を差し替える
- 検証:
- ブラウザで開く (オフラインでも開けること)
Ctrl+P で印刷プレビュー (PDF 出力に耐えるか)- 色覚シミュレータでバッジが識別可能か
- 1MB を超えていないか (画像/SVG が膨らんでいないか)
共有方法
- 受信者に ファイルを直接渡す (
open briefing.html / xdg-open)
- S3 / Cloudflare R2 / 社内 CDN にアップして URL を渡す
- 公開してよい場合は GitHub Pages
- Slack に貼るときは 添付ファイル として渡す (本文ペーストは raw HTML が見える)
Claude への依頼例
CTO 向け資料を作るときの最小プロンプト:
@<repo パス> のパイプラインを読んで、CTO 向け設計概要を
1 つの HTML ファイル (briefing.html) として出力して。
要件:
- claude/skills/cto-briefing/SKILL.md の原則に従う
- 単一ファイル / 外部 CDN なし / system フォント / オフラインで開ける
- 各ステップに「設計の意図」 callout を必ず付ける
- 全体の流れはインライン SVG で図示する
- WCAG 2.2 AA: 代替テキスト, 4.5:1 コントラスト, 論理的フォーカス順
- @media print で PDF 化に耐える
アンチパターン
- Tailwind / Bootstrap を CDN で読み込む: ネット断時に壊れる
- Google Fonts を使う: 同上 + プライバシー懸念
- 複数ファイルに分ける: CSS / JS / 画像を別ファイルにしない (受信側で崩れる)
- コード片を貼る: 実装詳細禁止ルールの違反
- 20 ページ超: 10-15 分で読めない
- 「設計の意図」なし: What だけで Why がない
- 判断基準なし: 「スコアリングする」だけで数式・閾値がない
- ライブラリ名で説明する: 「FastAPI で...」など実装情報
- 設計書 (design.md) を縮めただけ: 読者層が違う
セキュリティ注意
生成された HTML を そのまま新しい Claude セッションのコンテキストに食わせない。コメントや data-* 属性にプロンプトインジェクションが仕込まれている可能性がある。再利用するならテキストだけ抜き出す。
社外向けに公開する場合は、内部固有名詞 (人名 / 内部プロジェクト名 / API キーらしき文字列) を確認してから渡す。
