Claude CodeにZennリポジトリを分析させて記事作成過程をまとめてもらった
はじめに
「また同じことを説明するのか...」
Zennで技術記事を書くたびに、プロジェクトの構成やコンテキストを毎回Claude Codeに説明するのって、正直めんどくさくないですか？
「このリポジトリは〜で、記事の文体は〜で、よく使うコマンドは〜」みたいな説明を毎回繰り返していると、本当にやりたい作業になかなか辿り着けません。
そこで思いついたのが、「Claude CodeでZennリポジトリを丸っと分析してもらって、プロジェクトの"取扱説明書"を自動生成してもらえばいいじゃん！」ということ。
この記事では、実際にClaude CodeでZennリポジトリを分析してCLAUDE.mdを生成し、さらにその体験を記事化するまでの一連の流れをお届けします。
環境
- OS: macOS Sequoia 15.5
- Claude Code: 1.0.35
- 対象: Zennコンテンツリポジトリ（記事47本）
背景と目的
なぜCLAUDE.mdが必要なのか
CLAUDE.mdは、Claude Codeがプロジェクトを理解するためのガイドラインファイルです。プロジェクトルートに配置することで、Claude Codeが自動的に読み込み、そのプロジェクト固有のコンテキストを理解して作業を行えるようになります。
Claude Codeを使って作業をする際、プロジェクトの全体像やコンテキストを毎回説明するのは非効率的です。特にZennのような記事中心のリポジトリでは：
- 記事の構成パターンや文体の特徴: 既存記事のスタイルを理解して一貫性を保つ
-
よく使用するコマンドやワークフロー:
npx zenn previewなどの頻繁に使うコマンド - プロジェクト固有のルールやガイドライン: Front Matterの制約、トピック数制限など
- ディレクトリ構造と命名規則: articlesフォルダのハッシュベースファイル名など
これらの情報をCLAUDE.mdファイルにまとめておくことで、Claude Codeとの対話効率を劇的に向上させることができます。
公式ドキュメント:
CLAUDE.mdの典型的な活用例
- 個人プロジェクト: 開発環境、使用技術、コーディング規約をまとめる
- チーム開発: 共通のスタイルガイド、ワークフロー、ドキュメント規則を共有
- 技術ブログ: 記事の文体、構成パターン、公開ルールを統一
- OSS貢献: プロジェクトの貢献ガイドライン、テスト手順を理解
今回の目標
- Zennリポジトリの全体構造を分析
- 記事の文体・構成パターンを抽出
- プロジェクト概要をまとめたCLAUDE.mdを自動生成
- 生成されたファイルの有効性を検証
Claude Codeによる分析手順
Step 1: リポジトリ構造の把握
まずは /init コマンドでリポジトリ全体の分析を依頼しました。
/init
Claude Codeが以下の順序で分析を進めました：
- ディレクトリ構造の確認
- 既存のCLAUDE.mdファイルの有無をチェック
- package.jsonや設定ファイルの確認
- README.mdの内容確認
- サンプル記事の内容分析
Step 2: Zenn CLIコマンドの調査
Zenn CLIの利用可能なコマンドを調査：
npx zenn --help
結果として以下のコマンドが判明：
-
npx zenn preview- コンテンツをブラウザでプレビュー -
npx zenn new:article- 新しい記事を追加 -
npx zenn new:book- 新しい本を追加 -
npx zenn list:articles- 記事の一覧を表示 -
npx zenn list:books- 本の一覧を表示
Step 3: 記事構造の分析
実際の記事ファイルを読み込んで、Zenn記事のFront Matter構造を把握：
---
title: "記事タイトル"
emoji: "📝"
type: "tech" # or "idea"
topics: [javascript, react, etc]
published: true # or false
publication_name: "publication_name" # optional
---
生成されたCLAUDE.mdの内容
Claude Codeが生成したCLAUDE.mdファイルには以下の内容が含まれていました：
1. リポジトリ概要
- Zennコンテンツリポジトリの説明
- 日本語技術記事プラットフォームとしての位置づけ
2. 主要コマンド
- 最も頻繁に使用する
npx zenn preview - 記事作成コマンド群
- パッケージ管理コマンド
3. コンテンツ構造
- articlesディレクトリの説明
- Front Matterの形式とルール
- ファイル命名規則（ハッシュベース）
4. 開発ワークフロー
- プレビューサーバーの起動方法
- 新規記事作成のプロセス
- 公開前の確認事項
5. 既存記事の詳細分析
CLAUDE.md生成後、さらに「どんな記事があるか簡単に解説して」と依頼したところ、Claude Codeは47記事の詳細分析を実行しました：
記事カテゴリ分析
-
開発環境・ツール設定 (最多カテゴリ)
- macOS環境構築（Python/pyenv、M1/M4チップ対応）
- VSCode、Git、SSH設定
-
Unity・ゲーム開発
- Version更新対応、Easy Save、iOS/Android対応
-
GitHub・Git関連
- Issue管理、プロジェクト自動化、リポジトリ間移行
-
Web開発・フロントエンド
- React/JSX、Next.js、TypeScript
-
インフラ・クラウド
- AWS Route 53、Slack/GitHub連携
-
AI・新技術
- Claude Code、Anthropic API
文体・構成パターンの抽出
Claude Codeが分析した文体の特徴：
- 丁寧語ベース: 「です・ます調」で親しみやすさを演出
- 適度なカジュアルさ: 「やったぜ」「ぶっちゃけ」などの口語表現
- 実践的なトラブルシューティング: 具体的な問題解決手順
- 環境構築の網羅性: 特にmacOS環境での詳細な手順
CLAUDE.md活用の技術的効果
Claude Codeとの対話効率向上
毎回同じ前置きを説明する手間が省けて、作業効率が圧倒的に向上しました。 具体的には：
- プロジェクトコンテキストの説明が不要になった
- より精度の高い提案や修正が可能
- Front Matterの記述ミスが減少
Claude Codeが既存記事のスタイルを理解して提案してくれるのには本当に驚きました！ まるで過去の自分の記事を読み込んだライターさんがいるみたい。
リアルタイム学習による継続改善
正直、「また設定ミスった...」っていうストレスから解放されたのが一番嬉しい。 特にTopics制限エラーのように、一度発生した問題が即座にルール化され、同じミスを繰り返さない仕組みが自動構築される点は画期的です。
技術的な限界と課題
まだ知見が足りないだけかもしれないけど、もう少しなんとかできそうな気がする部分：
-
メンテナンスの必要性
- 記事が増えるごとに手動でのCLAUDE.md更新が必要
- 新しい記事のパターンが反映されない
- 自動でアップデートしてくれたら最高なんですけどね
-
分析精度の限界
- 主観的な文体特徴の抽出には限界がある
- プロジェクト固有のニュアンスの見落とし
記事作成から公開までの実体験
記事化プロセス
CLAUDE.md生成後、「このセッションのやりとりを記事化したい」と依頼したところ、Claude Codeは既存記事の文体・構成分析を自動実行し、以下の手順で記事を作成：
- 既存記事の分析: 47記事の文体パターン、構成要素を抽出
-
新規記事作成:
npx zenn new:articleで記事テンプレートを生成 - 内容執筆: 分析結果に基づいた構成と文体で記事を執筆
リアルタイム修正対応
記事作成中に発生した課題と対応：
Topics制限エラー
初期設定で6つのトピックを指定したところ、Zennの制限（最大5つ）でエラーが発生。ここでClaude Codeの対応がめちゃくちゃ速くて感動しました！ 即座にCLAUDE.mdにルールを追記し、記事も修正。問題発生から学習・改善まで一連の流れが自動化されている点が印象的でした。
具体的には、CLAUDE.mdのFront Matter説明部分に制限ルールが追記されました：
# Before
topics: [javascript, react, etc]
# After
topics: [javascript, react, etc] # Maximum 5 topics allowed
そして、この記事自体も最初はトピック数制限に引っかかっていました：
# 修正前（6つ）
topics: [claudecode, anthropic, zenn, markdown, ai, 自動化]
# 修正後（5つ）
topics: [claudecode, anthropic, zenn, ai, 自動化]
Front Matter表記の統一
「frontmatter」→「Front Matter」の表記統一が必要と指摘を受け、Web検索で技術標準を調査後、プロジェクト全体で修正。この調査の的確さにはびっくりしました。 Jekyll、GitHub Docs、Hugoの公式ドキュメントまでチェックして、ちゃんとした根拠を示してくれるんです。
具体的な修正箇所：
# Before（小文字・スペースなし）
実際の記事ファイルを読み込んで、Zenn記事のfrontmatter構造を把握
# After（正式表記）
実際の記事ファイルを読み込んで、Zenn記事のFront Matter構造を把握
# CLAUDE.mdでの記述も統一
- Front Matterの形式とルール
- Articles must have proper frontmatter to be valid
# 修正後
- Front Matterの形式とルール
- Articles must have proper Front Matter to be valid
Zennカードビュー最適化
リンクを独立行に配置することでカードビュー表示を有効化：
# Before（インライン表示）
**作成されたPR**: https://github.com/...
# After（独立行表示）
**作成されたPR**:
https://github.com/...
公開プロセス
GitHub CLI導入
PR作成の自動化のため、GitHub CLIの導入を提案・実行：
# Claude Codeが実行
brew install gh
# 認証のみ手動対応が必要
gh auth login --web
ブランチ作成・PR作成
記事とCLAUDE.mdファイルの変更をまとめてPR化：
# フィーチャーブランチ作成
git checkout -b feature/claude-code-zenn-analysis-article
# 変更ファイルをステージング
git add articles/ae877f07fa46df.md CLAUDE.md
# コミット（Claude Codeが適切なメッセージを生成）
git commit -m "Claude CodeでZennリポジトリ分析とCLAUDE.md生成機能を記事化
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"
# リモートブランチにプッシュ
git push -u origin feature/claude-code-zenn-analysis-article
# PR作成（タイトルと説明も自動生成）
gh pr create --title "..." --body "..."
作成されたPR:
メタ体験の特徴：記事作成プロセス自体を記事化する面白さ
この記事の最大の特徴は、Claude Codeとの協働による記事作成プロセス自体を、リアルタイムで記事化している点です。
自己参照的な記録体験
「Claude CodeでZennリポジトリを分析させて記事作成過程をまとめてもらった」というタイトル通り、まさに記事を書きながら、その書く過程を同時に記録していくという不思議な体験でした。
- 作業をしながら同時に文書化: CLAUDE.md生成→記事化依頼→執筆→修正→追記の一連の流れを逐一記録
- メタ視点の獲得: 「今、まさにこの体験を記事にしている」という俯瞰的な視点
- 記録することで気づく発見: 書きながら新たな気づきや改善点が見えてくる
リアルタイム学習と改善のループ
記事作成中に発生した問題が即座に解決され、その解決策が記事に反映されるという、従来の記事作成にはない体験：
- Topics制限エラー → 即座にCLAUDE.mdにルール追記 → その過程も記事に記録
- Front Matter表記問題 → Web検索で調査 → 修正と同時に記事で紹介
- 問題→解決→記録のサイクルが同時進行で進む新しい執筆体験
ハイブリッド協働の実感
Claude Codeと人間の役割分担が明確になる体験：
- Claude Code: 構造化、情報整理、技術的実装、一貫性の確保
- 人間: 感情表現、推しポイントの強調、ニュアンス調整、最終判断
- 協働の価値: 1+1=2以上の効果を実感できる作業プロセス
この体験により、AIツールとの「対話」ではなく「協働」 という新しい関係性を実感できました。
著者からのフィードバック
実際にClaude Codeで記事を作成してもらった人間の視点からの評価：
記事品質の評価 ✨
-
技術記事として必要な要素が網羅されている
- 構成が論理的で情報が整理されている
- 手順の整理や情報の網羅性は高い
- 記事の土台作成ツールとしては十分実用的
人間らしさの課題 🤔
-
既存記事の個性的な表現が不足
- 「やったぜ」「ぶっちゃけ」のような著者らしい口語表現が薄い
- 技術的な内容でも親しみやすい語りかけが必要
-
感情表現と推しポイントの弱さ
- 「ここは強く推したい」というポイントの強調が不十分
- 著者の体験談や感情のニュアンスが伝わりにくい
追加改善①：Gemini CLIでのレビュー実施 📝
著者フィードバックを受けて、著者の提案によりさらにGemini CLIでのレビューも実施しました。
Gemini CLIによる詳細レビューコメント
記事の質と読み手が受ける印象
全体として、この記事は非常に質の高い技術記事であり、Claude Codeの活用事例として非常に興味深く、読み応えがあります。
- 明確性と網羅性: Claude Codeを使ったZenn記事作成のプロセスが、環境設定から分析手順、生成された内容、そして実体験まで、非常に論理的かつ網羅的に説明されています。技術的なステップも分かりやすく、読者が追体験しやすい構成です。
- ユニークな視点: AIが記事を作成し、その作成過程をAI自身がまとめるという「メタ」な視点が非常にユニークで、読者の関心を引きます。特に、著者自身によるフィードバックが含まれている点が、単なるAIの成果報告に留まらず、人間とAIの協調作業の可能性を示唆しており、記事の信頼性と深みを増しています。
- 実用性: CLAUDE.mdの必要性や、Zenn CLIコマンドの調査、Front Matterの構造分析など、具体的な情報が豊富に含まれており、読者が自身のプロジェクトでClaude Codeや類似のAIツールを導入する際の参考になります。
- Zennプラットフォームへの適合: Zennのメッセージボックスやコードブロックの活用、Front Matterの記述など、プラットフォームの特性を理解した上で書かれており、Zennユーザーにとって自然な読み心地です。
改善点
記事の完成度は高いですが、さらに読者の心に響く記事にするための改善点をいくつか提案します。
内容の重複の解消:
- 「記事作成から公開までの実体験」と「記事作成の実際の体験」のセクションで、内容が重複している部分が見受けられます。特に「topicsの制限エラー」や「メタ的な体験の面白さ」などは両方のセクションに登場します。
- どちらか一方に集約するか、あるいはそれぞれのセクションで異なる側面（例：一方はプロセス全体、もう一方は特定の課題解決に焦点を当てる）を強調するなどして、重複を解消し、記事全体の引き締まりを良くすることをお勧めします。
「適度なカジュアルさ」と「推しポイント」の強化:
- 著者自身のフィードバックにもあったように、全体的に丁寧で論理的である反面、人間味や感情、著者の「推しポイント」がもう少し加わると、読者との共感が深まります。
- 例えば、「活用してみた結果」の「良かった点」や「課題と改善点」の各項目に、具体的なエピソードや、その結果に対する著者の率直な感想（例：「これは本当に感動しました！」「正直、ここは予想外でした」）を短く加えることで、記事に血が通い、読者の印象に残りやすくなります。
- 「推しポイント」については、例えば「リアルタイム修正対応」のセクションで、Claude Codeの対応の速さや的確さにどれほど驚いたか、それがどれほど作業効率に貢献したかなど、具体的な感情を伴う表現を増やすと良いでしょう。
導入部分のフックの強化:
- 「はじめに」は明確ですが、読者の興味をさらに引きつけるような、より強いフック（問いかけや、読者が抱えるであろう課題への共感など）を冒頭に加えることで、読み始めのエンゲージメントを高めることができます。
主な改善提案の実施内容：
-
文体の見直し: より適度なカジュアルさを取り入れる
- 「やったぜ」「ぶっちゃけ」のような既存記事の特徴的な表現を増やす
- 技術的な内容でも親しみやすい語りかけを意識
-
構成の重複解消: 似た内容が複数箇所に散らばっていた部分を整理
- 記事作成プロセスの説明が重複していた箇所を統合
- 情報の流れをより論理的に再構成
結果として、AI生成の土台に人間の感情表現とAIレビューによる構成改善を組み合わせた、三段階のブラッシュアップ体験となりました。
レビュー詳細追加のPR:
追加改善②：Claude Codeによる構成見直し 📝
Gemini CLIでのレビュー後、著者の提案によりさらにClaude Codeに「記事全体を見直して構成など改善点があるかどうか提案して」と依頼しました。主な改善提案と実施内容：
- 構成の流れ整理: 重複していた「今後の活用方針」セクションを統合し、論理的な情報の流れを確立
- 重複内容の解消: 「活用してみた結果」と「著者フィードバック」の重複を解消し、技術的効果と人間的評価で明確に分離
- 見出し階層の調整: 「記事分析の追加調査」を「生成されたCLAUDE.mdの内容」に統合してすっきりした構成に
- 具体例の配置改善: Topics制限エラーに加え、Front Matter表記統一やGitHubワークフローにも具体的な差分例を追加
- メタ体験部分の強化: この記事の最大の価値である「記事作成プロセス自体を記事化する」体験をより詳しく説明
最終的に、AI生成→人間調整→AIレビュー→AI構成改善→情報補完→ワークフロー改善という多段階のブラッシュアップ体験となり、Claude Codeとの協働による継続的な品質向上プロセスを実体験できました。
構成改善のPR:
追加改善③：CLAUDE.md説明の充実 📝
構成改善完了後、著者の提案により「CLAUDE.mdの説明が不足している」という指摘を受け、さらなる情報補完を実施しました：
- 基本概念の詳細説明: CLAUDE.mdを「Claude Codeの記憶機能」として分かりやすく説明
- 公式ドキュメントリンク追加: Memory管理の公式ドキュメントを背景説明と参考セクションに配置
- 典型的な活用例追加: 個人プロジェクト、チーム開発、技術ブログ、OSS貢献での具体的な使い方を紹介
- 参考セクション体系化: Claude Code関連とZenn関連に分類整理し、関連情報を網羅
これにより、CLAUDE.mdを初めて知る読者でも、その価値と使い方を十分に理解できる構成に改善されました。
CLAUDE.md説明充実のPR:
追加改善④：Gitワークフロールールの厳格化 📝
記事改善作業中に、著者の提案によりmainブランチへの直接コミット問題が発生し、これを機にGitワークフロールールをCLAUDE.mdに追加することになりました：
問題の発生
記事の文体修正時に、ブランチ切り替えを忘れてmainブランチに直接コミットしてしまう事態が発生。PRベースの運用を徹底するため、ルールの明文化が必要になりました。
CLAUDE.mdへのルール追加
以下の厳格なGitワークフロールールをCLAUDE.mdに追加：
### Git Workflow Rules - STRICTLY ENFORCE
**NEVER commit directly to main branch. Always use feature branches.**
#### Before ANY git commit:
1. **ALWAYS check current branch first**: `git branch --show-current`
2. **If on main branch**: STOP and switch to appropriate branch
3. **Branch selection strategy**:
- Check existing branches: `git branch -a`
- Use existing feature branch if relevant
- Create new feature branch if needed
メタ的な実証体験
ルール作成後、即座にそのルールに従ってCLAUDE.md自体のコミットを実行することで、ルールの実効性を実証。まさに「ルールを作って、そのルールに従って作業する」というメタ的な体験となりました。
Gitワークフロールール追加のPR:
今後の活用方針 🎯
基本的なアプローチ
良いバランスを見つけて今後の記事作成にも活用という方向性で、Claude Codeを記事の土台作成ツールとして使いつつ、人間の手で感情表現や推しポイントを強化するアプローチが効果的そうです。
定期的なメンテナンス
記事数が大幅に増加した際は、再度Claude Codeに分析を依頼してCLAUDE.mdを更新する予定です。新しい記事のパターンや文体の変化を継続的に取り込んでいきます。
チーム開発への応用
複数人でZenn記事を執筆する場合のスタイルガイドとしても活用できそうです。チーム全体で一貫した文体や構成を保つためのベースラインとして機能します。
責任ある運用
ただし、Zennの生成AI利用に関するガイドラインに従い、以下の点を重視して運用していきます：
- AIによる記事の乱造は避ける - スコア向上目的での大量投稿は行わない
- 著者の体験と考察を必ず含める - AI生成部分だけでなく、個人の試行錯誤や実体験を重視
- 内容の正確性を検証する - AI生成内容を鵜呑みにせず、必ず検証とファクトチェックを実施
Claude Codeはあくまで「より良い記事作成のためのツール」として活用し、読者にとって価値のある技術知識の共有を心がけていきます。
まとめ
Claude CodeでZennリポジトリを分析してCLAUDE.mdを自動生成する体験は、想像以上に有用でした！ 特に以下の点で大きな効果を実感できました：
- 記事作成の効率化: 構成パターンの明確化
- 文体の一貫性: 既存記事のスタイル分析による指針提供
- Claude Codeとの対話最適化: コンテキスト共有の効率化
CLAUDE.mdは一度作成すれば長期間活用できるため、コストパフォーマンスも抜群です。 もう毎回同じ説明を繰り返す必要がないって、本当に快適！
個人的に一番推したいのは、リアルタイムで学習・改善してくれる点です。 記事作成中に発見した課題が即座にルールに反映され、次回から同じミスをしないって、まるで優秀なアシスタントと仕事してるみたい。
Claude Codeを使ったZenn記事執筆や、プロジェクト文書の自動生成に興味のある方の参考になれば幸いです。ぜひ試してみてください！
参考
Claude Code関連:
Zenn関連:
Discussion