はじめに 🚀
VS Code + Gemini Code Assist(Agent/CLI)の環境ができたので、
最近注目のAIエージェントでの開発とGitOps × CI/CD 自動化を試すべく、お約束のテトリスを開発しながら、効率的なフォルダ構成とパイプライン設計を考え始めたメモになります。
Markdown-Driven Development（MDD）の目指す姿
AIエージェントでの開発はMDでの指示出しや設計が重要になりそう。
このためすべてをMDで管理、MD起動にて追跡、管理、再現性があり説明できる形にする。
合わせてEXCEL設計書からの脱却を図る。
フォルダ構成イメージ
project-root/
├── src/ # 実装コード
├── docs/ # ドキュメント類
│ ├── spec/ # 最新仕様・設計
│ ├── worklog/ # 調査・改善ログ
│ ├── rules/ # 規約・ガイドライン
│ ├── ai-gitops/ # GitLab/GitOpsに向けた将来構想
│ └── templates/ # MDテンプレート
├── tests/ # テストコード
└── README.md # リポジトリの案内（AI/人間が最初に読む場所）
フォルダの位置づけ(基本はすべてMDで記述)
- worklog/ … 開発・調査・不具合改修・機能追加など「起点」となるドキュメントで日付やイベントごとに残すMDの作業指示
- spec/ … 最新のMD設計書
- rules/ … コーディング規約や命名規則などプロジェクトの行動指針MD
- templates/ … 作業型MDテンプレート
ワークフローの流れ
-
スタート：
worklog/devYYYYMMDD.mdなどに作業方針を作成（ここはWebのChat GPTやClaudeと壁打ち） -
AIエージェントがコード作成支援：
src/を上記MDに基づいてGemini Agentと一緒に作業 -
レビュー・反映：仕様が確定したら
spec/に移動し最新状態へ反映（ここもAIにてMDやmermaidで作成） -
ナレッジ蓄積：頻出の作業は
templates/にテンプレートとして追加。またworklogにも経緯や知見が蓄積
ルートのREADME.mdの例
クリックして展開
# Python Tetris Project
## プロジェクト概要
このプロジェクトでは、**Python** を用いてシンプルな **テトリス風ゲーム** を実装します。
ローカル環境で動作する軽量なGUIゲームを想定しており、音声やグラフィックの派手な演出は行いません。
---
## 要件
- Python 3.x
- キーボード操作に対応（左右移動・回転・ドロップ）
- スコア表示機能
- ブロックが積み上がって一定ラインに達するとゲームオーバー
- 音声・効果音なし
- スタイリングは最低限でよい（可読性を優先）
- コーディングルールは `@docs/rules/design_rules.md` に準拠
- 背反する判断が発生した場合は、**必ず人間に確認**を取ること
---
## 開発環境
- Python 3.10+
- 推奨ライブラリ: `pygame`（軽量な2Dゲームライブラリ）
- 開発補助: Gemini Code Assist（仕様理解・コード補完・バグ検出など）
---
## ディレクトリ構成（案）
test-game/
└── tetris/
├── src/
│ ├── main.py # ゲームのメインループ、描画処理、イベントハンドリング
│ ├── tetris.py # テトリミノ定義、回転処理、ゲームボードロジック
├── tests/ # テストコード
├── assets/ # フォントやアイコンなど（必要に応じて）
└── README.md
---
## 実行方法（pygameを使用する場合）
```bash
# 初回のみ
pip install pygame
# 実行
python src/main.py
開発の流れ（想定）
-
tetris.pyにてブロック・ボード・衝突判定ロジックを実装 -
main.pyにてイベントループと描画処理を構築 - 最低限のスコア表示とゲームオーバー処理を実装
- コードレビューを実施（@docs/rules/design_rules.md に沿って）
ライセンス
MIT License（予定）
メモ
- Gemini Code Assist の補助を受けつつ、論理的な設計・ドキュメント整備を並行して進めます。
- AI補助で生成されたコードは、必ず人間がチェックを行い品質を担保してください。
docs/rules/design_rules.mdの例
## 開発ポリシー
- モジュールごとに関数を分け、1ファイル1責任
- 可読性優先（変数名・関数名は意味が分かるように）
- Gemini Code Assist の提案は都度チェックして反映
- AGPLライセンスは絶対に使用しないこと。ライブラリ提案時は依存関係を考慮すること。
- 引用元のライセンスがある場合は必ず明示すること。また商用ライセンスを侵害しないように最大限注意すること。
docs/worklog/dev20250712.mdの例
# 開発作業概要
本日はREADMEに従い、テトリス風ゲームを開発に着手する。
---
## ゴール
実装を行う。
メリット
- テンプレート活用によりAIの文脈精度向上や再現性が上がり、ジュニアにも展開可能
- CI/CD + Agent パイプラインで docs とコードの自動完全同期の時代へ
- 設計と実装が同時に進み、ある意味runnableな設計書が整備され、また速やかにレビュー可能
Agent by Gemini Code Assistと一緒に開発してみる。
🧠 実行例：Agentと共に開発してみる
- プロジェクトルールとして
README.mdとdesign_rules.mdを用意 - その日の作業用として
dev20250712.md（作業指示ファイル）をアクティブファイルにして作業開始
💡 Gemini Code Assist は README.md を読み、アクティブな .md を「指示」として扱ってくれます。
👇 開発の様子（スクリーンショット）
Step1: 環境構築
Step2: AIによる実装
Step3: 動作確認。3クリックでここまで！
細かいチューニングはここから対話しながら進める必要がありますが、mdファイル（Markdown）によってAgentに指示を出せることが分かりました。
🧠 実行例：コードレビューもしてみる。
Step4: コードレビューの提案もされます。
Step5: 修正案が出てきたので修正します。
design_rules.mdを最初からつけているのだから実装時から考慮してほしいですが、これはプロンプトを改良すればいいのだろうと思います。
Step6: 作業ログを残します。
きちんと作業を残してくれました。
作成された作業ログ
# 開発作業概要
本日はREADMEに従い、テトリス風ゲームを開発に着手する。
---
## ゴール
実装を行う。
---
## 作業ログ
- **環境構築**
- `pygame` ライブラリをインストールした。
- `src` ディレクトリに `main.py` と `tetris.py` を作成した。
- **基本機能実装**
- `tetris.py` にゲームのコアロジック（ブロック定義、ボード管理、衝突判定）を実装した。
- `main.py` にメインループ、描画処理、イベントハンドリングを実装した。
- `README.md` に従って、基本的なテトリスの動作（移動、回転、ライン消去、ゲームオーバー）を実装し、動作確認を行った。
- **コードレビューとリファクタリング**
- `docs/rules/design_ruls.md` に基づきコードレビューを実施した。
- 設定値を管理する `config.py` を作成し、コードの可読性と保守性を向上させた。
- イベント処理を関数に分離し、メインループを整理した。
- スコアに応じた落下速度の調整機能を追加した。
- **機能追加**
- 初期落下速度を調整した。
- スペースキーによるハードドロップ機能を追加した。
🧩 今後目指すところ：CI/CD × GitOps による自動同期
-
docs/worklog/にMRがマージされると、- AIが
spec/を自動更新 - 仕様差分のMRを自動生成
- AIが
-
コードとドキュメントが常に同期された状態を保つ、ドキュメント駆動型GitOps
✅ まとめ
- MDD（Markdown-Driven Development）とAIエージェントの相性は抜群
- Gemini Code Assist の活用で 再現性・省力化・説明性 が大きく向上
- 初期構成とルール整備で、チーム展開やCI/CD連携も視野に入る
本日はここまで。次回はGitHub Agentとの連携を行います。