Vibe coding実践例:継続的な拡張に備えるコード管理方針

前回まで、RSSフィードから記事本文を取得し、要約とXで投稿するコメント案をLLMで作成するところまで、Vibe codingでの実装を検証してきました。

ここまでの実装でコードの行数が200行を超え、これより先の拡張ではAIによるコーディング支援特有の問題が起こりやすくなります。

Vibe codingで本格的に拡張する前に、コード管理の方針を整理します。

管理方針
コードの分割
ドキュメントやスキーマの整備
Gitの導入
まとめ

管理方針

Vibe Codingは厳密な定義はありませんが、できるだけコードを意識しないことを目指します。

実際には、完全にコードをブラックボックスとする開発手法を推し進めると、規模の拡大で突然コードが動かなくなったり、予期しない動作が多発して破綻することも少なくありません。コードの分割、バージョン管理、ドキュメント整備など、”外枠”に当たる部分にソフトウェア開発の基本的な管理手法を取り入れることで、効率と品質を向上させることができます。

まずはコードを意識せず比較的簡単に取り入れられるものとして、以下の3点を推奨します。

コードの分割
GitおよびGitHubの導入
ドキュメントの整備

「コードを意識しないこと」にこだわらず、コードの中身に踏み込む場合は下記もおすすめです。

black, ruff等のコード整形ツール導入
共通化やライブラリ化の強化
テストの導入
CI/CDの導入

コードの分割

コードの分割は、Vibe codingの効率を上げるために重要です。 1つのソースコードが大きくなると、AIが全体を把握しづらくなり、保守性が低下します。

本シリーズのように、Python + VS Code + ChatGPTの場合、経験則から200行程度が1ファイルの上限の目安となります。これを超えると、インデントが深くなり、文字列・ヒアドキュメント・コメントの取り扱いでAIが混乱を起こしやすくなります。

またAIでパッチ編集を繰り返すと、import文や定数・変数をソースコードの頭にまとめず、関数やクラスの定義の近くに配置する傾向があり、コードの可読性が低下します。さらに、リファクタリング等の影響範囲が広くなり、AIによる修正漏れが起こりやすくなります。

初期段階にまとまった指示を与えるとAIが計画的に進める場合が多いのですが、段階的なパッチ編集を繰り返す機能拡張ではAI側からのリファクタリング提案はほぼ無いのが現実です。ある程度の規模の段階でコードが大きくなったら、AIにコード分割を提案させるか、自分で分割を指示することをおすすめします。

コードの分割についてはAIが案を出してくれますが、コードの依存性が小さくできる部分を分割のポイントとします。以下のような基準が考えられます。

機能ごとに分割する: RSS取得、本文取得、要約生成、コメント生成など、明確な機能単位でコードを分割します。
クラスや関数ごとに分割する: 大きなクラスや関数は、さらに小さな単位に分割して管理しやすくします
共通部分をライブラリ化する: 複数の箇所で使用される共通の処理は、別のモジュールとして切り出し、再利用性を高めます。
ドキュメントを分割する: 各モジュールや関数の説明を別ファイルにまとめ、理解しやすくします。

200行程度のコードではあまり起こりませんが、グローバル変数を多用したり、関数間の依存性が強い場合は、分割に時間がかかりすぎて失敗することもあります。 Gitでバージョン管理を行い、分割前の状態に戻せるようにしてから作業を行うと安心です。

RSS自動投稿コードの分割例

今回のRSS自動投稿コードは、ヒューマンインザループの形を取り、人間の操作を境界として2つのコードに分割する方向でアプローチします。 Markdown形式の利用、JSON形式での状態管理は、生成AIに相談するとよくある案として出てきます。コードの分割については、明示的に指示をしたほうが確実です。

自動投稿を定期的に繰り返す際、RSSフィードに含まれる新規記事のみを処理したい。
また、記事に対してコメント案を生成した後に、人間が内容をチェック・編集し指示したもののみXに投稿するようにしたい。
今後の保守性も考え、どのようにコードを分割し、データの管理を行うのが良いか提案をしてください。

Markdown形式でなくUIの構築を提案してくる場合もありますが、複雑になるため段階的に進めたほうが良いでしょう。またJSON形式の代わりにSQLiteなどのデータベースを提案してくる場合もありますが、まずはシンプルなJSON形式で始めるのが良いでしょう。

データはJSON形式で状態管理を行い、人間とのインターフェースとしてMarkdownファイルを使用します。大まかに下記の方針とします。ファイル名などは仮案です。

システム構成：

collect_and_prepare.py: RSS取得から要約・コメント生成、レビュー用MD出力まで
post_to_x.py: ユーザー承認後のX投稿とステータス更新
articles.json: 記事データとステータスの管理
review.md: 人間がレビュー・編集するインターフェース

この分割により、以下のメリットが得られます：

自動処理と人間の判断を明確に分離
途中でエラーが発生しても状態を保持
各コードが単一の責務に集中
テストや修正がしやすい

ただしこれは仮の設計で、実装を進めながら行数などを見て調整する必要があります。

ドキュメントやスキーマの整備

コード分割時、他のコードをimportして利用する場合は、関数やクラスの定義やコメントが重要な意味を果たします。

一方、今後取り扱うX自動投稿の例では、Markdown形式のファイルやJSON形式のファイルを介して複数のPythonコードが連携します。この時、コード間は直接の関連性がないため、仲介するファイルのドキュメントやスキーマの整備が重要になります。

Markdown形式は設計書または仕様書、JSONはスキーマの定義をドキュメント化してAIに渡すと、AIが迷いにくくなります。適切なドキュメントを用意せずにインプットを行わないと、AIは推測や一般論に基づいてコードを生成するため、デバッグが複雑になります。

X自動投稿コードのドキュメント例

今回、まずは処理の大枠を箇条書きで与えデータフローを出力してもらいました。

VS CodeのMarkdownプレビューで見やすくなるように、Mermaid記法でシーケンス図を生成するよう指示しています。(下記の図はmermaid.liveで作成、VSCodeとは若干異なる)
Online FlowChart & Diagrams Editor – Mermaid Live Editor。

処理フロー:

flowchart TB
    subgraph Code1["collect_and_prepare.py"]
        A[RSS取得] --> B[新規のみ本文取得し追加]
        B --> C[AI要約・コメント生成]
        C --> D[review.md出力]
    end
    
    subgraph Human["VS Code等でのMD編集"]
        D --> E[MD編集]
        E --> F{操作}
        F -->|チェック| G[投稿承認]
        F -->|編集| H[コメント修正]
        F -->|スキップ| I[投稿不要]
    end
    
    subgraph Code2["post_to_x.py"]
        G --> J[MD読込・検証]
        H --> J
        I --> J
        J -->|OK| K[X投稿]
        J -->|NG| L[エラー出力]
        K --> M[投稿ID保存]
    end
    
    JSON[(articles.json)]
    
    A -.ステータス管理.-> JSON
    B -.ステータス管理.-> JSON
    C -.ステータス管理.-> JSON
    M -.ステータス管理.-> JSON
    I -.ステータス管理.-> JSON
    
    style JSON fill:#f9f,stroke:#333,stroke-width:2px
    style Human fill:#9f9,stroke:#333,stroke-width:2px

データフロー：

sequenceDiagram
    participant RSS as RSSフィード
    participant Code1 as collect_and_prepare.py
    participant JSON as articles.json
    participant MD as review.md
    participant User as ユーザー
    participant Code2 as post_to_x.py
    participant X as X (Twitter)
    
    RSS->>Code1: RSS取得
    Code1->>JSON: 新規URL登録 (status: new)
    Code1->>Code1: 本文取得
    Code1->>JSON: 更新 (status: fetched)
    Code1->>Code1: AI要約・コメント生成
    Code1->>JSON: 更新 (status: ready)
    Code1->>MD: レビュー用MD出力
    
    Note over MD,User: 人間の操作フェーズ
    User->>MD: チェック/編集/スキップ
    
    MD->>Code2: 編集済みMD読み込み
    Code2->>Code2: 検証処理
    alt 投稿承認あり
        Code2->>X: 投稿実行
        X-->>Code2: 投稿ID
        Code2->>JSON: 更新 (status: posted)
    else スキップ指示
        Code2->>JSON: 更新 (status: skipped)
    else エラー検出
        Code2->>User: エラー出力・処理中断
    end