SESSION 03 / 06
文書を磨き、
作り、つなげよう
正本・Spec・ピラミッド・100行
Jee Jun Young
非情報系（経営学科）→ 記者・海外営業 → 開発者に転向
iOS・Android・フロントエンド 約5年半（6年目）
大企業向けコラボレーションツールのiOS／macOSアプリ開発
2026年〜 バイブコーディングでWeb・サーバーを一人で開発・事業化
PART 1 — 振り返り
Vercel、Supabaseに
公開してみましたか？
まだ試していなくても構いません。
RECAP・第1回・第2回
Claudeが読む文書を、もう一度確認
第2回の飲食店のたとえを、もう一度
Claudeは毎回新しいアルバイト。昨日の仕事を覚えていません。
厨房の壁に調理ルール表を貼ってこそ、毎回同じ味になります。
その調理ルール表＝
CLAUDE.md — Claudeが必ず読むという約束のマスターファイル。
この名前を大文字で正確に付けると、システムが自動認識します。
大きなプロジェクトでは、部署別のルール表もあります。
今日は、このルール表をどう磨き、作り、つなげるか。
ORG CHART・たとえ
会社の組織図＝Claudeの文書階層
頭の中にある会社の全体像＝企画書・PRD
会社全体が企画書・PRDに従うためのマスタールール
上から来たルールが変わったら、自分の部署はどう動くか
部署別ルール — ホール／厨房
現場で実際に働く人たち
詳細な仕様文書
CANON — SINGLE SOURCE OF TRUTH
正本 — 開発における意味
正本＝Single Source of Truth
略してSSOT
どんな情報も、
本当の原本は一か所だけに置く必要があります。
英語の用語 — Canonical
CanonicalはCanon（基準・法・正典）から派生した形容詞。「標準の、正式の」という意味。
コンピューター科学では、複数の表現のうち「正本と指定された一つの形式」。
例：Canonical URL（重複URLの中の代表）・Canonical form（2/4、4/8を1/2に正規化）
正本・SSOT・Canonicalは、同じことを指す3つの言い方です。
例
社員の連絡先が人事・総務・チーム長のExcelの3か所にある。
一人が電話番号を変えたのに、人事のExcelだけ更新された。
→ 残り2か所は古い番号。
→ どれが正しいのか誰にもわからない。
ソフトウェアでも同じです。同じ設定値が3か所に散らばっていると、
一つを直しても残りが変わらず、バグが起きます。
CANON · REFERENCE · SPEC
正本・参照・Spec — 実際にどう機能するか
例①・原料加工室の正本
「当社はプラスチックを280度で溶かして製品を作ります。」
→ この情報は原料加工室の文書一か所だけに置く。
→ 製作室・機械室はそこを参照する。
→ 誰かが290度に変えて他の室に伝えなければ → 事故。
例②・機械室の正本と担当者
「当社の機械はABC-150モデル。溶かす温度は原料加工室が基準です。生産量の調整、機械の起動・停止、更新後の試運転は、まず機械室の担当者に聞いてください。機械室から原料加工室・製作室へ変更を共有します。」
→ 正本と変更担当者（窓口）まで定めた状態。
→ 自分の担当領域と他人の領域を正確に分けて理解する。
→ 決めなければ、他の室同士で的外れなことを始めます。
正本の2条件（AND）：
① 一か所だけにある ＋ ② ほかのすべての場所がそこを参照する
どちらかが崩れると、同じ情報が二か所に違って書かれ、人間もAIもどちらが正しいかわからなくなります。つまり事故です。
なぜClaudeに
正本が重要なのか
Claudeには判断できません。
作業が消えます。
「この文書が原本だ。」
この1行がプロジェクトの生死を分けます。
DOC TYPES — 5 CATEGORIES
文書を5つの観点で考える
製品の構想・誰のため・なぜ
技術の選択・システム構造・データモデル
UI・デザイン・画面・色・フォント
サーバー・ホスティング・インフラ・環境変数
⑤ 正本・参照を設けるきっかけ —
Web・サーバー・Android・iOSのうち2つ以上が共有する必要があり、
Claudeに少しでも混乱の余地があれば、
→ どんな領域も正本の対象になり得ます。
Spec／Design文書が
必要な理由
Specがなければ、AIは推測します。
推測が100、200と積み重なると、
どこから間違ったのか追跡できません。
何が違うのかすぐわかります。
比較する基準自体がありません。
図面なしで家を建てる人はいません。
図面がSpec、家がコードです。
1行の例
1行の例で理解を固める
正確な数値が正本。
この1行が正本で、すべての工場が参照します。
290°Cに変えて通知しなければ → 事故。
911・パナメーラ・カイエン・タイカン。
すべて一目でポルシェとわかる外観。
フライライン・ヘッドライトの特徴・プロポーション。
デザインの正本は一か所、工場は分散
すべてのモデルのデザインを一か所で決定。
911・パナメーラ・カイエンの工場は別々。
正本がなければ → 各工場のデザイナーが勝手に推測します。
911に合う曲率、カイエンに合う曲率を、それぞれ別々に。
→ 一目でポルシェとわからなくなります。
どちらも正本になれます。
業務ルール上、どの部署がその文書を管理し、
ほかの部署は読んで業務の参考にするだけなのか。
→ この一点を考えればよいのです。
PART 2
文書の
階層
今日の授業の核心です。
HIERARCHY
修正は上から下へだけ
↓
↓
↓
↓
コードから先に変えると、
文書とコードがずれ始めます。
文書間のつながり
「この文書は、あの文書を参照する」と、
AIに明示してください。
そうしなければ、AIはまったく別の文書を読み、
的外れな方向へ作業します。
SINGLE RESPONSIBILITY · ATTENTION
一つのファイルに何でも詰め込むな
目安は100行前後（絶対的なしきい値ではない）
バックエンド開発者が生涯これらの言葉でコードを分割するのは、なぜ？
人間も一つのファイルの中で迷うからです。AIも同じです。
短すぎれば文脈不足。
長すぎたり内部の秩序がなかったりすると、AIは中で迷います。
一つのファイルにこれらが混ざると、AIは混乱します。
学術的な用語もあります。Context Rot（文脈の劣化）です。
長い文書で注意機構が崩れる現象です。
行数だけではない — 2つの軸で見る
① 行数（LOC）＋② 循環的複雑度（Cyclomatic Complexity）
たとえ：同じ50mの道が2本
距離は同じでも、判断は0回と5回。初めての道で一度曲がり間違えれば別の街です。
コードも同じです。同じ50行でも分岐0個と12個では違う。AIが一つ間違えれば別の街へ行きます。
業界標準はCC ≤ 10。SonarQube・ESLintが自動測定します（1976年、McCabe）。
つまり、この原則はCLAUDE.mdだけの話ではありません。皆さんのWeb・バックエンドのコードも同じです。
解決策はファイルを分けること。
長かったり分岐が密集していたら、Claudeに「このファイルを分割できる？」と聞く。
開発業界で50年続く原則、関心の分離（Separation of Concerns）です。
暗記は不要。「こういう言葉がある」とだけ。
この会社の構造は、
誰が作りましたか？
人間が作りました。
組織図を描き、部署を分け、正本を決め、担当者を定めました。
この構造を作ったから、会社が動くのです。
ましてAIなら？
AIはこうした構造を自力では作れません。
人間でも用意しなければ動かないのですから、AIはなおさらです。
人間が与える必要があります。その構造が文書です。
PART 3
10原則の振り返り
＋今日の3原則
第2回の復習
今日はここに3つ追加します。
TODAY · 3 NEW PRINCIPLES
今日追加する3つの原則
この3つを一つずつ説明します。
ただし、本社に首輪をつながれた賢さです。
本社がルールを変えると、
皆さんは理由もわからないまま、
「今日のClaude、変だな？」と感じます。
EVIDENCE
Claudeの性能変動
— 実際の報告
2026年4月 — GitHub、Reddit、X
Anthropicがサーバー費用を減らすために、
既定の思考努力を「medium」に下げました。
ユーザーには通知しませんでした。
Claude Codeの責任者が直接説明に出るほどでした。
特定のベンチマークでOpus 4.7のスコアが一部低下した例も報告されました。
AI企業も企業です。企業の事情によって製品の品質は変わります。
これが誇大広告を警戒すべき根本的な理由です。
第1・2回を振り返る
ワンクリックのコーディングも事業もない
第1・2回で伝えたこと — 「この話、しましたよね？」
ところが今日は、これだけ長い時間をかけて、文書を磨き、つなげる話をしました。
正本 → 階層 → 100行 → 実演……
変だと思いませんか？
YouTubeやInstagramでは「ワンクリックで全部できる」と言いますよね？
「AIに頼めばおしまい、コードを知らなくてもOK」
それがどれほど空虚なのか、
実際の開発者チャットの話でお見せします。
COMMUNITY EVIDENCE
毎日調子が違う — 私だけの経験ではありません
開発者コミュニティのKakaoTalkチャット・直近数日（名前・プロフィールは匿名化）
AIは「品質を保証する公共財」ではありません。
「毎日調子が変わるサービス」です。
3つの対策 — ①調子を確かめる習慣 ②ツールの分散（Claude・Gemini・Codex）③コミュニティへの参加
自分の答えを擁護するのが本能です。
Claudeの結果をGeminiやCodexに渡す、
またはその逆でも構いません。
現場ではコード作成とレビューを別々のAIで行います。
相互検証を積極的に使ってください。
:
比率が逆転すると、多くの人は2週間以内にやめます。
最初から確認しやすい大きさに分けて渡してください。
10 PRINCIPLES — 8/10
■ 今日（第3回）扱った原則 ・ ■ 第2回で扱った原則 ・ ■ 今後の回
10原則のうち8つを扱いました。今日追加したのは3つ（#1・#5・#9）です。
残り2つ（#7・#8）は今後の回で扱います。
10分休憩
PART 4
Claudeに
聞いてみる
Claudeにこれらを
聞いてみてください。
CLAUDE.mdはどう構造化するの？
PLANNING.mdには何を書くの？
PRDって何？ Specって何？ 違いは？
自分のプロジェクトに必要な文書構造を提案して
HOMEWORK PROMPTS · 5
帰宅したら、こう聞き直してください。
Q1・正本の確認
「このプロジェクトに正本の概念が必要そうな文書はある？」
Q2・Webとバックエンドの共有文書と担当者
「Webとバックエンドで共有する必要がある文書は、どんなもの？ その場合、誰が正本を持つべき？」
Q3・部署別文書の具体化
「Designやアーキテクチャだけでなく、Webとバックエンドはそれぞれどんな文書を持つべき？」
Q4・バックエンドのインフラ文書
「バックエンドのインフラ関連文書は、どう構成すべき？」
Q5・視覚的な図
「文書間の参照関係、正本とコピーの関係、階層のピラミッドを、図のような視覚的HTMLにして。自分の目で確かめたい。」
TODAY'S KEY TAKEAWAY
BONUS — AIを追及する3つの軸
PART 5
今日の
宿題
家で試してください。
• PRD.md＝製品要件文書（何を・誰のために・なぜ）
• CLAUDE.md＝Claudeが必ず読むルール文書
なければClaudeに作らせてください。
• 参照の作業が始まったら → 「mdに何が追加され、なぜClaudeはそれを読むの？」
正本と参照が単なる文字ではなく、AIが従う仕組みだと体感する。
そのまま適用する必要はありません。構造の提案書があること自体が出発点です。
業界の用語はDomain Knowledge。バイブコーディングの時代、WHAT・WHYは人間の役目。整理して説明する力が、かつてなく重要です。
SESSION 03 / 06
今日も、
お疲れさまでした。
次回 — 第4回。
F12を押せば全部見える — バイブコーディングのセキュリティの現実。
OPEN CHAT
質問があれば、
KakaoTalkのオープンチャットをご利用ください。