この投稿は、2025年JINSのアドベントカレンダー25日目の記事です。
JINSで、システムアーキテクト/プラットフォームエンジニアをしている佐藤(@Takuma3ato)です。
今、AIエージェントが盛り上がってますね。私は、Amazon Q Developerが統合されたKiroを使い始めました。Kiroは仕様駆動開発を謳っており、単にプログラムコードをAIに生成してもらうだけではなく、開発プロセスのもっと上流の方からアプローチしていく手法を組み入れることで、システム開発の世界でいうところの「シフトレフト」を実現しようとしていると私は捉えています。
さて、この仕様駆動開発のようなことを既に実装していた国産OSSがあったことをみなさん知っていますか？その名もZoltraakです。
キービジュアルがかっこいいですね！
このZoltraakは、漫画『葬送のフリーレン』に登場してくる一般攻撃魔法Zoltraakから付けられています。そういえば、葬送のフリーレンの第二期が2026年初頭から始まるみたいなので楽しみです。この漫画はアニメ化されていて、アニメの演出・声優もとても素晴らしく、世界観がとても好きです。制作会社はMADHOUSEという会社でアニメ制作能力の高さが伺えます。この会社は、映画では、「サマーウォーズ」「時をかける少女」や、アニメでは、「葬送のフリーレン」「チ。-地球の運動について-」「ワンパンマン」「DEATH NOTE」「蒼天航路」などを手掛けられており、私の好きなアニメが目白押しな制作会社です。
話が逸れてしまいましたが、、、今日は、このZoltraakを使ってみた時のことを記事にしたいと思います。
まず初めに、ささっと結論を知りたい方向けのまとめからです。
3行まとめ
・Zoltraakは、基盤モデルを指定しプロンプト用いて要求からコードを生成する
・「アーキテクト」や「開発者」などのロール定義しているプロンプトから要求を処理する
・Zoltraakを通してAIエージェントの仕組みを考えることができる
いかがですか？これは面白そうですよね。
というわけで、Zoltraakがどのように動くのか処理の全体像の説明から入りたいと思います。
全体像
Zoltraakができること
添付のようなシステム開発プロセスがあった時に、この上流から下流までを幅広く対応できるような可能性を持っています。色付けした箇所がZoltraakで処理できる範囲という理解です。
Zoltraakの処理プロセス
実際にどのように動くのかというと、操作としては自然言語をターミナルから打ち込んで、システムプロンプトが生成モデルに食わせる最適な文章を作成して、生成モデルから返ってきた情報を更に加工し、最終的な開発成果物(プログラムコード)を作るという流れです。
システムアーキテクチャ
Zoltraakを動かすために複雑なアーキテクチャは不要で、ローカルPCにPythonが実行できる環境があれば動きます。私はMac環境で、pipx(パッケージインストールツール)、uv(バージョン管理、仮想環境管理)で動かしています。
実際に使ってみる
Zoltraakをターミナルで動かし、開発成果物を作ってみたいと思います。(ローカルPC環境の構築手順は今回の記事では記載しません。)ZoltraakのPythonプログラムはこのような構成になっています。
コマンドを受け付ける
cli.pyがユーザからのコマンド入力を制御していて、以下のようなオプションを受け付けられるようなっています。別途、自分で自由にオプションを追加し、該当するコードも追加しやすいようになっています。
def main():
parser = argparse.ArgumentParser(description="MarkdownファイルをPythonファイルに変換します")
parser.add_argument("input", help="変換対象のMarkdownファイルのパスまたはテキスト", nargs='?')
parser.add_argument("--output-dir", help="生成されたPythonファイルの出力ディレクトリ", default="generated")
parser.add_argument("-p", "--prompt", help="追加のプロンプト情報", default=None)
parser.add_argument("-c", "--compiler", help="コンパイラー（要件定義書のテンプレート）")
parser.add_argument("-f", "--formatter", help="コードフォーマッター", default="md_comment")
parser.add_argument("-cc", "--custom-compiler", help="自作コンパイラー（自作定義書生成文書）")
parser.add_argument("-v", "--version", action="store_true", help="バージョン情報を表示") # 追加: バージョン情報表示オプション
parser.add_argument("-l", "--language", help="出力言語を指定", default=None) # 追加: 汎用言語指定オプション
args = parser.parse_args()
･･･
要求に関わる部分
システムプロンプトを用いて、生成モデルへ要件定義書や設計書などの上流工程の成果物の作成指示をするのは、md_generator.py が担っています。
def generate_md_from_prompt(
goal_prompt,
target_file_path,
developer="gemini",
model_name="gemini-2.0-flash", # この時はGemini2.0を使いました
compiler_path=None,
formatter_path=None,
language=None,
open_file=True,
):
if compiler_path is not None and "grimoires" in compiler_path:
prompt_compiler = os.path.basename(compiler_path)
else:
prompt_compiler = compiler_path
･･･
コードを生成する
次に、その上流工程の成果物を使い、生成モデルへプログラムコードの作成指示をするのはgencode.py が担っており、TargetCodeGeneratorクラスにある様々なメソッドを用いて、プログラムコードを生成します。こちらも専用のシステムプロンプトがあります。
class TargetCodeGenerator:
def __init__(self, source_file_path, target_file_path, past_source_file_path, source_hash):
self.source_file_path = source_file_path
self.target_file_path = target_file_path
self.past_source_file_path = past_source_file_path
self.source_hash = source_hash
def generate_target_code(self):
"""
ソースファイルからターゲットファイルを生成するメソッド
"""
# 1. 準備
create_domain_grimoire, target_dir = self.prepare_generation()
# 2. ソースファイルの読み込みと変数の作成
source_content, source_file_name, variables = self.load_source_and_create_variables()
# 3. プロンプトの読み込みとコード生成
prompt, code = self.load_prompt_and_generate_code(create_domain_grimoire, variables)
# 4. 生成されたコードの処理
self.process_generated_code(code)
# 5. 結果の出力
self.output_results()
･･･
開発プロセスの反復をする
最後に、converter.py は、Zoltraakを使うユーザ体験を良くすることが考えられているモジュールです。MarkdownToPythonConverterクラスには、Markdownファイル（要件定義書やプロンプト）とそれをインプットに生成されたPythonファイルの間の整合性を取るための提案をするようなメソッドがあり、AIによる開発サイクルが作られていることが特徴です。対象の成果物の差分チェックは、ハッシュ値を使うことで高速に判定を行っています。
class MarkdownToPythonConverter:
def __init__(self, md_file_path, py_file_path, prompt=None, compiler_path=None, formatter_path=None, language=None):
self.md_file_path = md_file_path
self.py_file_path = py_file_path
self.prompt = prompt
self.compiler_path = compiler_path
self.formatter_path = formatter_path
self.language = language
# self.client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
self.client = genai.Client(api_key=os.environ.get('GEMINI_API_KEY'))
･･･
def handle_existing_target_file(self):
with open(self.target_file_path, "r", encoding="utf-8") as target_file:
lines = target_file.readlines()
if len(lines) > 0 and lines[-1].startswith("# HASH: "):
embedded_hash = lines[-1].split("# HASH: ")[1].strip()
if self.source_hash == embedded_hash:
if self.prompt is None:
subprocess.run(["python", self.target_file_path])
else:
with open(self.target_file_path, "r", encoding="utf-8") as md_file:
md_content = md_file.read()
return md_content
else:
print(f"{self.source_file_path}の変更を検知しました。")
print("ソースファイルの差分:")
if os.path.exists(self.past_source_file_path):
self.display_source_diff()
･･･
システムプロンプト(魔導書)が重要
これまでに何度か話に出てきているシステムプロンプトの類は、zoltraak/grimoiresに入っています。グリモアはフランス語で「魔術の書物」を意味しており、Zoltraakの世界観を構成しているコンポーネントと言えます。要件定義書などの上流工程の成果物の作成、プログラムコードの生成などの指示が格納されています。このgrimoires で好きな魔導書を格納することでZoltraak魔法が更に進化するということですね。
grimoires/ % tree
.
├── architect
│ ├── architect.md
│ ├── architect_claude.md
│ ├── architect_daiagrams.md
│ ├── architect_detail.md
│ ├── architect_detail_dir.md
│ ├── architect_develop.md
│ ├── architect_functor.md
│ └── architect_gemini.md
├── compiler
│ ├── biz_consult copy.md
│ ├── biz_consult.md
│ ├── book_lecture_main.md
│ ├── book_lecture_quiz.md
│ ├── dev_akirapp.md
│ ├── dev_aws.md
│ ├── dev_front.md
│ ├── dev_func.md
│ ├── dev_obj.md
│ ├── dev_obj_lisp.md
│ ├── dev_obj_lisp_g.md
│ ├── dev_obj_lisp_g_base64.md
│ ├── dev_obj_mermaid.md
│ ├── dev_pypi.md
│ ├── dev_react_fastapi.md
│ ├── dev_reveal_rite.md
│ ├── dev_reveal_strict.md
│ ├── dev_streamlit.md
│ ├── dev_streamlit_mini.md
│ ├── encode_lisp.md
│ ├── front_faq.md
│ ├── front_hp.md
│ ├── general_def.md
│ ├── general_reqdef.md
│ └── ref_create_directory.py
├── developer
│ ├── dev_csharp.md
│ └── dev_python.md
･･･
そして最後に、使用する生成モデルを利用する処理は、
zoltraak/llms に入っています。私は、Geminiが好きなのでgemini.pyを使います。ただ、GitHub上に上がっているモジュールはimport google.generativeai as genaiで古いGemini SDKになっているので、from google import genaiを利用します。
Geminiのモデルについては、こちら
Geminiを利用する場合は、API Keyの発行をしてください。
Google AI StudioでKeyを発行すると無料で使えます
import os
from google import genai
from dotenv import load_dotenv
load_dotenv() # ここで .env を読み込んでセットする
api_key = os.environ.get('GEMINI_API_KEY') # 設定ファイルからキー情報を取得する
if api_key is None:
raise ValueError('GEMINI_API_KEY environment variable not set.')
client = genai.Client(api_key=api_key)
def generate_response(model='gemini-2.0-flash', prompt='Please, say hello'):
response = client.models.generate_content(
model=model,
contents=prompt
)
return response
# 使用例
response_text = generate_response('gemini-2.0-flash', 'prompt')
print(response_text.text)
魔法の効果を確認する
さて、いろいろ見てきましたが、Zoltraak魔法の素材と魔導書を使って、ふんわりした要求をしても良い感じの成果物が生成されるかを見てみましょう。
# Pythonを実行する仮想環境の構築については記載しません
source <FolderPath>/zoltraak/.venv/bin/activate
環境をアクティベートしたら、Zoltraakを詠唱しましょう！
zoltraak "アイウエア(メガネ)を販売するECサイトを作りたい" -c dev_obj`
ちなみに、-c はプロンプトコンパイラを指定するコマンドオプションで、dev_obj は、「オブジェクト指向設計を用いた開発タスクに関する要件定義書を生成するコンパイラ」ということのようです。既出のzoltraak/grimoiresにオブジェクト指向設計を定義するシステムプロンプトのファイルがあります。
Okay, I'm ready! Please provide me with your prompt. I'm eager to see what you want me to do. I can:
* Write stories
* Generate poems
* Translate languages
* Answer questions
* Summarize text
* Write code
* Create content of various kinds
* And much more!
Just let me know what you'd like me to do. I'm excited to get started.
Please provide me with the prompt you would like me to respond to. I need the prompt in order to generate a helpful answer. For example, you could ask me to:
* **Write a story:** "Write a short story about a robot who learns to love."
* **Answer a question:** "What are the benefits of regular exercise?"
* **Translate something:** "Translate 'Hello, how are you?' into Spanish."
* **Summarize a text:** "Summarize the main points of the article about climate change."
* **Generate code:** "Write a Python function that calculates the factorial of a number."
I'm ready to help once you give me the prompt!
language: None
要件定義書執筆中: def_eyewear_ec.mdは新しいファイルです。少々お時間をいただきます。
ステップ1. 起動術式を用いて魔法術式を構築する
==============================================================
起動術式 (プロンプトコンパイラ) : dev_obj.md
魔法術式 (要件定義書) : def_eyewear_ec.md
錬成術式 (プロンプトフォーマッタ) : md_comment_lang.md
言霊 (LLMベンダー・モデル 名) : gemini/gemini-2.0-flash
ファイルを開く : True
==============================================================
･･･
おー、ドキドキしますね。
使用する生成モデルやローカルPC環境のスペックによって処理時間に差は出ると思いますが、数分程度で完了します。
そして、成果物が<FolderPath>/zoltraak/generatedに配置されました。その一部を記載します。Markdown形式でドキュメントが作成され、該当の機能のPythonコードが生成されました！
% tree
.
├── ec_admin
│ ├── README.md
│ ├── config.py
│ ├── docs
│ │ ├── architecture.md
│ │ ├── deployment.md
│ │ └── requirements.md
│ ├── requirements.txt
│ ├── src
│ │ ├── controllers
│ │ │ ├── cart_controller.py
│ │ │ ├── order_controller.py
│ │ │ ├── payment_controller.py
│ │ │ ├── product_controller.py
│ │ │ └── user_controller.py
│ │ ├── database
│ │ │ ├── database_connection.py
│ │ │ └── migrations
│ │ │ └── initial_migration.py
│ │ ├── main.py
│ │ ├── models
│ │ │ ├── cart.py
│ │ │ ├── order.py
│ │ │ ├── payment.py
│ │ │ ├── product.py
│ │ │ └── user.py
│ │ ├── services
│ │ │ ├── cart_service.py
│ │ │ ├── order_service.py
│ │ │ ├── payment_service.py
│ │ │ ├── product_service.py
│ │ │ └── user_service.py
│ │ ├── utils
│ │ │ └── authentication.py
│ │ └── views
│ │ ├── cart_view.py
│ │ ├── order_view.py
│ │ ├── payment_view.py
│ │ ├── product_view.py
│ │ └── user_view.py
│ └── tests
│ ├── test_cart.py
│ ├── test_order.py
│ ├── test_payment.py
│ ├── test_product.py
│ └── test_user.py
･･･
機能要件に関するドキュメントもMarkdown形式で生成されています。
# ## ECサイト 機能要件定義書
#
# **1. 全体概要**
#
# 本ドキュメントは、ECサイトの機能要件を定義するものである。本ECサイトは、顧客が商品を閲覧・購入できるフロントエンド機能、事業者側が商品を登録・管理できるバックエンド機能を提供する。
#
# **2. 対象読者**
#
# * プロジェクトマネージャー
# * 開発チーム
# * テスター
# * 運用チーム
#
# **3. 用語定義**
#
# * **ユーザー:** ECサイトを利用する顧客
# * **事業者:** ECサイトに商品を出品する事業者
# * **管理者:** ECサイト全体の管理を行う担当者
# * **商品:** ECサイトで販売される物品
# * **カート:** ユーザーが購入予定の商品を一時的に保管する場所
# * **注文:** ユーザーが確定した購入内容
# * **決済:** 注文に対する支払い処理
#
# **4. 機能一覧**
#
# | 機能ID | 機能名 | 説明 | 優先度 | 備考 |
# |--------|---------------------------|-------------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------|
# | F001 | ユーザー登録 | ユーザーがアカウントを作成する機能。 | 高 | メールアドレス認証を含む |
# | F002 | ログイン | ユーザーが登録済みの情報でログインする機能。 | 高 | パスワードリマインダー機能を含む |
# | F003 | ログアウト | ユーザーがログイン状態を解除する機能。 | 高 | |
# | F004 | 商品検索 | ユーザーがキーワードやカテゴリで商品を検索する機能。 | 高 | 絞り込み、並び替え機能を含む |
# | F005 | 商品詳細表示 | 商品の詳しい情報を表示する機能。 | 高 | 商品画像、価格、在庫数、説明文、レビューなどを表示 |
# | F006 | カートに追加 | ユーザーが商品をカートに追加する機能。 | 高 | 数量指定機能を含む |
# | F007 | カート内容表示/編集 | ユーザーがカートの内容を確認し、数量を変更したり商品を削除したりする機能。 | 高 | |
# | F008 | 注文手続き | ユーザーがカートの内容を確認し、配送先や支払い方法を選択して注文を確定する機能。 | 高 | |
# | F009 | 注文履歴表示 | ユーザーが過去の注文履歴を確認する機能。 | 中 | 注文日、注文番号、商品名、金額、配送状況などを表示 |
# | F010 | 注文キャンセル | 注文後、一定時間内であれば注文をキャンセルできる機能。 | 中 | キャンセルポリシーを明示 |
# | F011 | 決済処理 | クレジットカード決済、銀行振込、コンビニ払いなど、複数の決済方法に対応する機能。 | 高 | セキュリティを考慮した安全な決済処理を行う |
# | F012 | 商品登録 | 事業者が商品を登録する機能。 | 高 | 商品名、価格、在庫数、説明文、画像などを登録 |
# | F013 | 商品編集 | 事業者が登録済みの商品を編集する機能。 | 高 | |
# | F014 | 商品削除 | 事業者が商品を削除する機能。 | 中 | |
# | F015 | 在庫管理 | 事業者が商品の在庫数を管理する機能。 | 高 | |
# | F016 | 注文管理 | 事業者が注文状況を確認し、発送処理などを行う機能。 | 高 | 注文状況のステータス管理（未処理、処理中、発送済、完了） |
# | F017 | 売上レポート | 事業者が売上状況をレポートとして確認できる機能。 | 中 | 期間指定、商品別、顧客別など、様々な切り口で分析 |
# | F018 | ユーザー管理 | 管理者がユーザー情報を管理する機能。 | 低 | ユーザーの権限管理（一般ユーザー、管理者） |
# | F019 | CMS機能（コンテンツ管理） | 管理者がECサイトのコンテンツ（お知らせ、FAQ、利用規約など）を更新できる機能。 | 中 | |
# | F020 | レビュー機能 | ユーザーが商品に対してレビューを投稿できる機能。 | 中 | 評価、コメント投稿、レビュー表示 |
# | F021 | お気に入り機能 | ユーザーがお気に入りの商品を登録できる機能。 | 中 | |
# | F022 | おすすめ商品表示 | ユーザーの閲覧履歴や購買履歴に基づいておすすめ商品を表示する機能。 | 中 | アルゴリズムの検討が必要 |
# | F023 | メール通知機能 | 注文確認メール、発送通知メールなどを自動送信する機能。 | 高 | テンプレート管理機能を含む |
# | F024 | セキュリティ対策 | セキュリティ脆弱性に対応するための機能。 | 高 | SQLインジェクション対策、クロスサイトスクリプティング対策、個人情報保護対策 |
# | F025 | アクセス解析 | サイトへのアクセス状況を分析する機能。 | 中 | Google Analytics連携など |
# | F026 | 多言語対応 | 複数言語に対応する機能。 | 低 | 必要に応じて実装 |
# | F027 | スマートフォン対応 | スマートフォンでの閲覧・操作に最適化されたレスポンシブデザインとする機能。 | 高 | |
# | F028 | API連携 | 外部サービス（配送業者API、決済代行サービスAPIなど）との連携機能。 | 中 | 必要に応じて実装 |
# | F029 | ポイントシステム | 購入金額に応じてポイントを付与し、次回以降の買い物に利用できる機能。 | 中 | ポイント付与率、有効期限などを設定可能 |
# | F030 | クーポン機能 | 特定の条件を満たすユーザーにクーポンを発行し、割引を受けられる機能。 | 中 | クーポンコード発行、利用条件などを設定可能 |
# | F031 | 検索サジェスト機能 | ユーザーが検索キーワードを入力する際に、候補を表示する機能。 | 中 | 検索履歴や人気キーワードに基づいてサジェスト |
# | F032 | FAQ機能 | よくある質問とその回答を掲載する機能。 | 中 | ユーザーの自己解決を促進 |
# | F033 | お問い合わせフォーム | ユーザーがECサイト運営者へ問い合わせできる機能。 | 高 | 問い合わせ内容の管理機能を含む |
･･･
まとめ
「ECサイト作りたいなー」な簡単な一言でここまでの成果物が作られるのはすごいですね。
とはいえ当然ながら、生成された仕様情報が完全であるわけはなく、またPythonコードもそのままリリースして良いものではありませんので、人の介在は必要です。
しかし、システムプロンプトの改善、使用する生成モデルの進化、AI開発フローとしての改修を通して更に良いツールになると思いました。
この記事が、バイブコーディングや仕様駆動開発の仕組みの理解につながれば幸いです。
では、また。
Discussion