🎯 概要
Markdownドリブン開発（MDD） を実現すべく、
Gemini Code Assistに加えGitHub + GitHub Actionsを活用し、
ドキュメント更新のCI/CDを構築します。
✅ STEP1：前回の続き
🛠 1. 前回の続きで以下を進めておきます。
- テストコードを作成
- GitHubのリポジトリ作成とpush
ちなみにワークログ（dev20250712.md）にてテストコード作成まで行い、作業終了時の作業ログ更新の際にテストパターンまで記載を指示するときちんと記載してくれます。
dev20250712.mdをクリックして展開
開発作業概要
本日はREADMEに従い、テトリス風ゲームを開発に着手する。
ゴール
実装を行う。
作業ログ
-
環境構築
-
pygameライブラリをインストールした。 -
srcディレクトリにmain.pyとtetris.pyを作成した。
-
-
基本機能実装
-
tetris.pyにゲームのコアロジック（ブロック定義、ボード管理、衝突判定）を実装した。 -
main.pyにメインループ、描画処理、イベントハンドリングを実装した。 -
README.mdに従って、基本的なテトリスの動作（移動、回転、ライン消去、ゲームオーバー）を実装し、動作確認を行った。
-
-
コードレビューとリファクタリング
-
docs/rules/design_ruls.mdに基づきコードレビューを実施した。 - 設定値を管理する
config.pyを作成し、コードの可読性と保守性を向上させた。 - イベント処理を関数に分離し、メインループを整理した。
- スコアに応じた落下速度の調整機能を追加した。
-
-
機能追加
- 初期落下速度を調整した。
- スペースキーによるハードドロップ機能を追加した。
-
テストコード実装
-
unittestを用いてtetris.pyのコアロジックに対するテストコードを作成した。 -
testsディレクトリを作成し、test_tetris.pyを配置した。 - モジュールインポートの問題を解決し、すべてのテストが成功することを確認した。
-
テストシナリオ一覧
test_tetris.py にて、以下のシナリオを検証しています。
-
test_initial_state: ゲーム開始時にスコアが0、ゲームオーバーフラグがFalse、ボードが空であること。 -
test_piece_creation: 新しいテトリミノがボードの上部中央に正しく生成されること。 -
test_rotation: テトリミノが正しく90度回転すること（Iミノを例に検証）。 -
test_collision_with_wall: テトリミノが左右の壁と床に正しく衝突すること。 -
test_collision_with_other_piece: テトリミノが、既にボードに存在する他のブロックと正しく衝突すること。 -
test_clear_lines: ラインが揃った際に、正しく消去されスコアが加算されること（1行および複数行）。 -
test_game_over: 新しいブロックが生成された時点で、その場所が他のブロックと重なっている場合に、正しくゲームオーバーになること。
📂 本日の最終形の構成
test-game/
└── tetris/
├── src/ # ソースコード
├── tests/ # テストコード（追加）
├── docs/
│ ├── worklog/ # 作業ログMarkdown
│ ├── spec/ # 自動生成された設計書
│ └── template/ # 設計書テンプレート（AI用）（追加）
├── scripts/ # Github Actions用コード）（追加）
├── .github
│ └── workflows/ # Github Actions用設定（追加）
├── Gemini.md # Gemini特化のRedameファイル
└── README.md
🧩 ポイント
-
Markdownに始まり、Markdownに終わる開発フロー
-
docs/worklog/以下に日付付き作業ログを作成。メンバーへの作業指示と作業報告に使える想定。 -
docs/spec/最新ドキュメントを配置。ここのメンテのCI/CD化を目指す。 -
README.mdにプロジェクト概要などを記述
-
🛠 2. 現時点の設計書（spec）をAgentで作ります。
worklogにdev20250712-2.mdを作り、以下の作業指示を行います。
# 開発作業概要
本日はREADMEならびにソースを参考に設計資料（spec）をMarkdownで作成する。
---
## ゴール
以下のテンプレートに従って、`src/`, `docs/worklog/`, `README.md` を参考に設計資料を作成してください。
- ファイル構成、処理フロー、キー操作などを網羅すること
- Mermaid記法で処理フロー図を1つ入れること
- 拡張予定や制限事項もREADMEと照合して整理すること
テンプレートファイル：docs/template/design_documents_template.md
出力ファイル：docs/spec/design_documents.md
---
## 作業ログ
※ 作業後、AIまたは手動により作業内容がここに追記される。
以下のdesign_documents_template.mdも用意します。
クリックして展開
# 設計資料（自動生成用テンプレート）
このドキュメントは、プロジェクトのコード・作業ログ・READMEをもとに、設計情報をMarkdown形式で記述するためのテンプレートです。
AIによる自動生成・更新を想定しています。
---
## 目的と概要
※ このソフトウェアの目的と概要を記述してください。
例：本プロジェクトは Python + pygame を使用したテトリスゲームの実装である。
---
## 処理概要とフロー
※ 全体的な処理の流れを説明し、Mermaid で可視化してください。
処理フローの例
## モジュール構成とその仕様
## 設定値
## 画面仕様
## 操作仕様
## 拡張予定（未実装）
## 制限事項
design_documents.mdが作成されました。
クリックして展開
設計資料
このドキュメントは、プロジェクトのコード・作業ログ・READMEをもとに、設計情報をMarkdown形式で記述したものです。
目的と概要
本プロジェクトは Python + pygame を使用したテトリスゲームの実装であり、MDD（Markdown Driven Development）とAIエージェントによる共同開発の実験を兼ねている。
処理概要とフロー
ゲームは main.py の main() 関数から実行される。Pygameを初期化し、ゲームのメインループを開始する。メインループでは、ユーザーからのキー入力を処理し、ゲームの状態を更新し、画面を描画する。
モジュール構成とその仕様
-
main.py: ゲームのメインループ、描画処理、イベントハンドリングを担当する。-
draw_board(): ゲームボードを描画する。 -
draw_piece(): 現在操作中のテトリミノを描画する。 -
draw_score(): スコアを表示する。 -
draw_game_over(): ゲームオーバー画面を表示する。 -
handle_input(): キーボード入力を処理する。 -
main(): ゲームのメイン処理。
-
-
tetris.py: テトリスゲームのメインロジックを管理する。-
Tetrominoクラス: テトリミノを管理する。-
rotate(): テトリミノを90度回転させる。
-
-
Tetrisクラス: テトリスゲームのメインロジックを管理する。-
new_piece(): 新しいテトリミノを生成する。 -
check_collision(): テトリミノとボードの衝突判定。 -
lock_piece(): テトリミノをボードに固定する。 -
clear_lines(): 揃ったラインを消去し、スコアを更新する。 -
update(): ゲームの状態を1フレーム進める。 -
hard_drop(): テトリミノを一番下まで一気に落とす。
-
-
-
config.py: ゲームの設定値を管理する。
設定値
config.py で定義されている主な設定値は以下の通り。
-
SCREEN_WIDTH,SCREEN_HEIGHT: スクリーンサイズ -
GRID_SIZE: グリッドサイズ -
BOARD_WIDTH,BOARD_HEIGHT: ボードサイズ -
SHAPE_COLORS: テトリミノの色
画面仕様
- ゲーム画面は
config.pyで定義されたSCREEN_WIDTHとSCREEN_HEIGHTに基づいて作成される。 - ゲームボード、操作中のテトリミノ、スコアが画面に表示される。
- ゲームオーバー時には "GAME OVER" というテキストが画面中央に表示される。
操作仕様
- 左矢印キー: テトリミノを左に移動
- 右矢印キー: テトリミノを右に移動
- 下矢印キー: テトリミノを下に移動
- 上矢印キー: テトリミノを回転
- スペースキー: テトリミノを一番下まで一気に落とす（ハードドロップ）
拡張予定（未実装）
- 音声・効果音の追加
- より詳細なグラフィックや演出
制限事項
- 音声・効果音はない。
- スタイリングは最低限。
✅ STEP2：GitHub Actions によるSpec自動生成の仕組み導入
GitHub Actionsを動かすために以下の設定を行います。
🛠 1. スクリプト準備（scripts/generate_spec.py）
from pathlib import Path
import subprocess
OUTPUT_PATH = Path("docs/spec/design_documents.md")
def get_git_diff_summary():
try:
result = subprocess.run(
["git", "diff", "--cached", "--name-status"],
capture_output=True, text=True, check=True
)
diff = result.stdout.strip()
if not diff:
return "\n\n---\n\n**変更履歴**:\n（差分はありません）"
diff_lines = diff.splitlines()
summary = "\n".join(f"- {line}" for line in diff_lines)
return "\n\n---\n\n**変更履歴**:\n" + summary
except subprocess.CalledProcessError as e:
return f"\n\n---\n\n**変更履歴**:\nGit差分取得エラー: {e}"
if __name__ == "__main__":
current = OUTPUT_PATH.read_text(encoding="utf-8") if OUTPUT_PATH.exists() else ""
updated = current + get_git_diff_summary()
OUTPUT_PATH.write_text(updated, encoding="utf-8")
...
テンプレートを読み込んで design_documents.md に展開。今はdiffをコピーするだけです。
🛠 2. Actions設定（.github/workflows/update_spec.yaml）
# .github/workflows/update_spec.yml
name: Update Spec Document
on:
push:
paths:
- 'src/**'
- 'docs/worklog/**'
jobs:
generate-spec:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.10'
- name: Install Dependencies (if any)
run: pip install -r requirements.txt || true
- name: Generate Spec Document
run: python scripts/generate_spec.py
- name: Commit & Push Changes
run: |
git config --global user.email "github-actions@users.noreply.github.com"
git config --global user.name "github-actions[bot]"
git add docs/spec/design_documents.md
git diff --quiet && git diff --staged --quiet || git commit -m "docs: auto-update design_documents.md"
git push
🛠 3. 設計書の修正（doc/spec/design_documents.md）
design_documents.md側にもGitHub Acitonsのフックを入れます。
spec += "\n\n" + get_git_diff_summary()
🛠 4. 上記 1.～3.のpush
GitHub Actionsを動かすリポジトリにpushしておきます。
⚙ 5. GitActionsのパーミッション設定
- GitHub → [Settings] → [Actions] →
Workflow permissionsをRead and writeに変更
（デフォルトでは Push が 403 で拒否される）
✅ STEP3：軽微なリファクタリングを行い更新を確認
worklogにdev20250712-3.mdを作り、以下の作業指示を行います。
# 開発作業概要
GitHub Actions の動作確認のため、小規模なリファクタリングを行い、
CI により `docs/spec/design_documents.md` が自動更新されるかを検証する。
---
## ゴール
- コードの軽微なリファクタリングを行う（一時停止ポーズ機能を追加する）。
- Push によって GitHub Actions がトリガーされ、`spec` が自動で更新されること。
---
## 作業ログ
※ 作業後、AIまたは手動により作業内容がここに追記される。
✅ 検証結果
- 機能追加（一時ポーズ機能の追加）を行い
git pushしました。 - 自動的に
docs/spec/design_documents.mdが更新されたことを確認 -
git log上にもコミット履歴が反映
またGiuhub上のActionsからもWorkflowが動いたことが確認できます。
ただし残念ながら現時点ではうまく差分が差し込めていないようです。
spec += "\n\n" + get_git_diff_summary()
---
**変更履歴**:
（差分はありません）
まずは、チームメンバーのアクティビティを、一つのlogにまとめそれを管理者がAgentでスペックに反映していくのが現実的かなと思いました。GitActionsとAIの連携をさせてもドキュメント数が増えてきたときに少し厳しそうに見えます。
✅ まとめ
- feature追加 → worklog作成 → 実装・テスト → worklog更新 → git push → spec 更新のサイクル確立が見えて来ました。
また今回構築した部分は以下のgit push から GitHub Actions を通じて spec への追記の流れになります。
✅ 説明補足
-
git push：ローカルでの変更を GitHub に反映 -
GitHub Actions：.github/workflows/update_spec.yamlにより自動実行 -
generate_spec.py：設計ドキュメントへ差分追記 -
design_documents.md：docs/spec/にある設計資料 -
git commit & push：CI内で自動的にdocs/spec/design_documents.mdを更新し、リポジトリに反映
✅ ここまでと今後の見通し
| 項目 | 状態 |
|---|---|
| Markdown開発方針 | ✅ 導入済 |
| 作業ログ活用 | ✅ 日次追跡中 |
| GitHub Actions連携 | 🚧自動log更新整備中 |
| 今後の展望 | 🔜 .md`ドリブンをNotionやBacklogとも連携 |