Claude Cowork とNotion ドラフトをリポジトリに落とすまでの運用（概念）

ビジネスの現場において、企画書や要件定義のドラフトはNotionで作成され、実装や管理はGitHub（リポジトリ）で行われるという「二重管理」は避けて通れない課題です。しかし、Notionに書かれた抽象的なアイデアを、正確にMarkdownドキュメントやコードとしてリポジトリに反映させる作業は、これまで多大な人間による「手作業」を必要としてきました。

この断絶を解消する強力なソリューションが、AnthropicがリリースしたCLIツール「Claude Code」です。本記事では、Web UI版のClaude（Cowork）で思考を整理し、ターミナル上で動くClaude Codeを用いて、Notionのドラフトをリポジトリへ自動的に落とし込む実務的な運用フローを解説します。

Notionからリポジトリへ。Claude Codeを中心とした「ドキュメント・コード同期」の新標準

なぜNotionドラフトとリポジトリの間には「断絶」が生まれるのか

多くのプロジェクトにおいて、非エンジニアやPMはNotionを好みます。その柔軟なエディタとデータベース機能は、アイデアの「発散」に最適だからです。一方で、エンジニアリングの現場では、バージョン管理、レビューフロー、デプロイとの連動が不可欠なため、情報はGitHubなどのリポジトリに集約される必要があります。

この両者の間には以下の「断絶」が存在します。

• 構造の差：Notionのページ構造は自由度が高すぎるが、リポジトリには厳格なディレクトリ構造（docs/等）が求められる。
• 更新の遅延：Notionが更新されても、リポジトリ内のドキュメント（README.mdや仕様書）が更新されず、情報の「鮮度」が失われる。
• 翻訳コスト：Notionの「話し言葉」に近いドラフトを、技術的に正しいMarkdownやコードへ変換する作業が苦行である。

Claude Codeが果たす役割：ドキュメントを「動く仕様書」へ変換するエージェント

ここで登場するのが Claude Code です。従来のChatGPTやClaude（Web版）との決定的な違いは、「あなたのローカルファイルシステムに直接アクセスし、コマンドを実行し、ファイルを編集し、Gitコミットまで完結できる」という点にあります。

Notionからコピーした「やりたいことリスト」をClaude Codeに渡すだけで、彼はリポジトリ内の既存構成を読み取り、適切なディレクトリに適切なフォーマットでファイルを生成し、さらにはビルドチェックまで行うことができます。

Excelと紙の限界を突破する「Google Workspace × AppSheet」業務DX完全ガイドでも触れている通り、情報の入り口（入力）と出口（基盤）を繋ぐ仕組みこそがDXの本質です。本稿ではその「入り口」をNotion、「基盤」をリポジトリ、そして「繋ぎ」をClaude Codeが担います。

【実務アーキテクチャ】Claude Cowork（Web）と Claude Code（CLI）の役割分担

運用を最適化するためには、Web版のClaude（本稿ではコラボレーションの意味を込めて「Claude Cowork」と呼びます）と、CLIツールの「Claude Code」を正しく使い分ける必要があります。

Claude Cowork：思考の深化と大規模ドラフトの構造化

Notionに散らばった乱雑なメモを、いきなりClaude Code（CLI）に流し込むのは非効率です。まずはWeb版（Claude 3.5 Sonnet）の広いコンテキストウィンドウを活用します。

• 主な用途：Notionからのコピペによる要件の要約、プロジェクトの全体方針の策定、複雑なUI/UXロジックの壁打ち。
• 成果物：構造化された「実装指示書（Markdown）」や「CLAUDE.md」のドラフト。

Claude Code：リポジトリ操作と「CLAUDE.md」に基づく自動実装

Web版で固まった方針を「実行」に移すのがClaude Codeの役目です。ローカルマシンにインストールされたClaude Codeは、リポジトリの全ファイルをスキャンし、現状のコードベースとの整合性を保ちながら作業を進めます。

• 主な用途：新規ファイルの作成、既存ドキュメントの修正、テスト実行、Gitコミット、プルリクエスト作成。
• 特徴：claude コマンドを叩くだけで、エージェントが自律的にリポジトリ内を動き回ります。

ツール比較表：Web UI vs CLI (Claude Code)

実践ステップ：NotionのドラフトをClaude Codeでリポジトリに反映する

具体的な運用手順をステップバイステップで解説します。

STEP 1：Notionドラフトの書き出しとClaude Coworkへのインプット

まず、Notionで作成した要件定義やマニュアルのドラフトをコピーします。これをWeb版のClaude（Claude 3.5 Sonnet推奨）に貼り付け、以下のプロンプトを実行します。

「このNotionのドラフトから、技術リポジトリに含めるべき『docs/requirements.md』と、Claude Codeへの指示書となる『CLAUDE.md』の内容を生成してください。技術スタックはNext.jsとTypeScript、ドキュメントはMarkdown形式とします。」

STEP 2：CLAUDE.md による「プロジェクトの定義」

Claude Codeの最大の特徴は、カレントディレクトリにある CLAUDE.md というファイルを自動的に読み込み、その指示に従う点です。ここに「このプロジェクトのルール」を記述します。

CLAUDE.md の記述例

コーディング規約: TypeScript strictモード、Prettier適用

ドキュメント規約: 全てのドキュメントは docs/ 配下に配置し、日本語で記述

コミット規約: プレフィックスに feat:, docs:, fix: を使用

ビルドコマンド: npm run build

STEP 3：Claude Code（CLI）によるファイル生成とリポジトリ反映

ターミナルを開き、リポジトリのルートで claude コマンドを起動します。起動後、以下の指示を投げます。

実行例：

> Notionから生成したこのドラフト内容を docs/feature-A.md として新規作成し、既存の README.md にリンクを追加して。その後、ビルドが通るか確認してコミットまでお願い。

Claude Codeは以下のステップを自動で行います。

1. docs/feature-A.md を作成。
2. README.md を読み込み、目次セクションにリンクを追記。
3. npm run build を実行してエラーがないか確認。
4. git add . および git commit -m "docs: add feature-A from Notion draft" を実行。

SaaSコストとオンプレ負債を断つ。バックオフィス＆インフラの「標的」と現実的剥がし方で解説しているような、複雑なインフラの移行手順書作成なども、NotionのメモからClaude Code経由でリポジトリ管理に移行することで、属人化を劇的に防ぐことができます。

STEP 4：承認フローとプルリクエストの作成

Claude Codeは自律的に動きますが、勝手にプッシュさせるのは危険です。デフォルトではファイルの変更ごとに「Allow? (y/n)」と確認を求めてきます。全ての作業が終わったら、以下のコマンドでプルリクエスト作成まで指示できます。

> GitHub CLI(gh)を使って、この変更を 'feature/notion-sync' ブランチにプッシュして、PRを作成して。

Claude Codeを使い倒すための「コンテキスト管理」術

AGENTS.md を活用したサブエージェント化の概念

大規模なプロジェクトでは、Claudeが読み込むべき情報が多すぎて精度が落ちることがあります。その際に有効なのが AGENTS.md です（※開発コミュニティで提唱されているパターン）。

• 役割の明確化：例えば「UIドキュメント担当」「APIリファレンス担当」といった役割ごとにMarkdownファイルを作成し、Claude Codeにそのファイルを読み込ませて特定のタスクに集中させます。
• Skillsの活用：Claude Codeに特定のスクリプト（例：Notion APIから特定のページを引っ張ってくるPythonスクリプト）を「Skill」として認識させ、実行させることも可能です。

既存ドキュメントの読み取りと差分抽出の自動化

Notion側が更新された際、「何が変わったのか」を人間が探す必要はありません。Notionの最新テキストをClaude Codeに貼り付け、「既存の docs/ 配下のファイルと比較して、差分がある箇所を全て修正して」と指示するだけで、リポジトリが最新の状態に保たれます。

楽楽精算×freee会計の「CSV手作業」を滅ぼす。経理の完全自動化とアーキテクチャのような、データの整合性が命となるプロジェクトにおいて、この「差分更新」の自動化はミスを根絶する鍵となります。

導入時の注意点とエラー対処法

セキュリティ：.gitignore と機密情報のスキャン

Claude Codeは強力なエージェントですが、誤って .env ファイルなどの機密情報をドキュメントに書き込んでしまうリスクがあります。

• 対策1：リポジトリのルートに .claudeignore を作成し、Claudeに読み取らせたくないパス（環境変数、バイナリファイル、node_modules等）を明記します。
• 対策2：Claude Codeにコミットを依頼する前に、必ず git diff を自分の目で確認するか、機密情報検知ツール（gitleaks等）をプリセットしたスクリプトをClaude Code自身に実行させます。

コスト管理：トークン節約のための claude_ignore

Claude Codeは実行のたびに現在のリポジトリのファイル構成をコンテキストに含めます。巨大なリポジトリの場合、一度の命令で数円〜数十円のトークン代が発生します。

• 対処：不要なログファイルや画像、ビルド生成物は必ず .claudeignore に含め、Claudeが読み取る情報量を最小限に抑えてください。

まとめ：AIエージェントが繋ぐ「ドキュメント」と「エンジニアリング」

Claude Codeの登場により、Notionという「思考の場」と、GitHubという「実行の場」の距離はかつてないほど縮まりました。これまで人間が泥臭く行ってきた「ドラフトからドキュメントへの転記」や「仕様変更に伴うコードの微修正」は、もはやAIエージェントに任せるべきタスクです。

本記事で紹介した、CLAUDE.mdによるルール定義とClaude CodeによるCLIベースの実装フローを導入することで、プロジェクトの透明性と更新速度は飛躍的に向上します。まずは小規模なドキュメント管理から、Claude Codeの力を試してみてください。

3. **追記するHTMLだけ**（通常は `