project-builder

フェーズ 0: スキルの探索と必読資料

⚠️ 重要 — UI デザイン品質ゲート: プロジェクトが何らかの視覚的な HTML 出力 (ダッシュボード、Web アプリ、ランディングページ、ポートフォリオ、ユーザーが目にするあらゆるページ) を生成する場合、HTML/CSS を書く前に必ず read_file で ui-design スキルの SKILL.md を読み、それに従ってください。これは任意ではありません。project-builder はエンジニアリングを担当し、ui-design は視覚的な品質を担当します (そして、手書きではなく shadcn/ui、HeroUI、coss ui などのコンポーネントライブラリを使うべきタイミングを教えてくれます)。ui-design をスキップすると、ありきたりな AI スロップが出来上がります。

A. ソースとツールを選ぶ。 調査と API ドキュメントには Web 検索を使用してください。最新の市場数値や外部アクションについては、インストール済みの関連スキルを再利用してください。使用前にその SKILL.md を読み、見つからないスキルは auto_install=false で検索し、ユーザーの承認を得た場合にのみインストールしてください。独自の API コードは、その操作をカバーする適切なスキルがないことを確認した後にのみ書いてください。エンドポイントとレスポンスの形式は、最新の公式ドキュメントと照合して検証してください。

B. プロジェクトが触れる部分についてプラットフォームのルールを読む。 これらのルールは (システムプロンプトではなく) リファレンスにあるため、コードを書く前に read_file で読む必要があります。これをスキップすることが、401 エラー、壊れたパス、「ローカルでは動いたのにプレビューで失敗する」バグの最大の原因です。

プロジェクトに含まれるもの...	フェーズ 2 の前に read_file するもの
外部 API 呼び出し	config/context/references/sc-proxy.md
プレビュー / ダッシュボード / Web アプリ	config/context/references/preview-guide.md
スケジュールされたタスク	config/context/references/scheduled-tasks-guide.md
長時間実行されるバックグラウンドジョブ	config/context/references/background-tasks.md
300 行を超えるファイル書き込み	config/context/references/tool-writing-guide.md
何らかの視覚的な HTML 出力 (ダッシュボード、Web アプリ、ランディングページ、ポートフォリオ)	ui-design スキルの SKILL.md — これを読み込み、すべての視覚的な判断 (トラックの選択、色、タイポグラフィ、レイアウト、アニメーション、コンポーネントライブラリを使うべきタイミング) に従ってください。このスキルは UI 品質ゲートです。スキップすると、ありきたりな AI スロップが出来上がります。

---

フェーズ 1: 設計

曖昧なリクエストを具体的な仕様に変換します。 意図が不明確な場合は、質問を 1 つだけしてください。

アーキテクチャの意思決定ツリー:

Periodic alerts/reports?  → Scheduled Task
Live visual interface?    → Preview Server (dashboard)
One-time analysis?        → Inline (no build needed)
Reusable tool?            → Script in workspace

中規模以上のプロジェクトでは、コードを書く前にユーザーに提示してください:

1. データフロー — ソース → 処理 → 出力
2. アーキテクチャの選択とその理由
3. コスト見積もり — (コスト/実行) × 頻度 × 30 = 月額
4. 既知の制限

UI デザインゲート (必須、ブロッキング — 視覚的なプロジェクト向け): アーキテクチャの選択がプレビューサーバー、またはユーザーが目にする HTML を出力するあらゆるプロジェクトである場合:

1. read_file で ui-design スキルの SKILL.md を今すぐ読み (このセッションでまだ読んでいない場合)、トラック (手書き vs コンポーネントライブラリ) を選んでください。
2. 手書き UI の場合、Design Dials (ui-design の references/design-process.md 内) を実行して、Surface、Accent、Typography、Aesthetic Family を決定してください。
3. 以下のフェーズ計画に Design Dials の出力行を含めてください。 このステップをスキップすると、UI はありきたりな AI 出力のようになります。このゲートはブロッキングです — 完了せずにフェーズ 2 に進まないでください。

デザインゲート: 多段階の作業では、短いフェーズ計画を提示してください。ユーザーがすでに明確で可逆的な実装を承認している場合は、同じ承認を再度求めずに進めてください。尋ねるのは、スコープが本当に曖昧な場合、重要なコストの承認が必要な場合、または次のアクションが不可逆的/外部向け (公開、送信、取引、削除) の場合だけにしてください。アクティブなプランモードは、ユーザーが実行を承認するまで読み取り専用のままです。

---

フェーズ 1.5: SCAFFOLD（共有可能なプロジェクトでは必須）

設計が確定したら、コードを書く前に、標準レイアウトでプロジェクトを scaffold します。これにより、初日から community-publish スキルでプロジェクトを共有可能になります — 後からの移行は不要です。

標準のプロジェクト配置場所: output/projects/{slug}/

output/projects/{slug}/
├── project.yaml          # name, version (start 0.1.0), type, description, license, entry, env_required
├── PROJECT.md            # 4 required sections: What / Required env / How to start / Outputs / Troubleshooting
├── .env.example          # every env var the code reads, with placeholder values
├── .gitignore            # at minimum: .env, *.key, *.pem, __pycache__, node_modules
└── src/                  # all code lives here, NOT scattered
    ├── run.py            # type=task — first line MUST be: # -*- task-system: v3 -*-
    ├── server.py         # type=service
    ├── main.py           # type=script
    └── index.html / app.py + frontend  # type=preview

プロジェクト種別 → エントリの対応:

アーキテクチャの選択	type	entry path
Scheduled Task	task	src/run.py
Preview Server	preview	src/index.html（静的）または src/app.py
Background daemon	service	src/server.py
One-shot tool	script	src/main.py

scaffold を省略するのは次の場合のみ:

• 永続的なコードを伴わない純粋なインライン分析
• 既存の output/projects/... プロジェクトの変更（そのレイアウトを維持する）
• ユーザーが「/tmp にスクリプトを置くだけでいい」などと明示的に言った場合

フェーズ 2 BUILD では、scaffold を維持します:

• コードが読み取る新しい環境変数 → 同じ編集で .env.example に追加する
• 動作の変更 → PROJECT.md を更新する
• src/ の外にコードを書かない（configs、fixtures: プロジェクトルートまたは src/data/）

これが重要な理由: すでに標準レイアウトにあるプロジェクトは 1 コマンドで公開できます。tasks/、output/scripts/、dashboards/ などに散在しているプロジェクトは、共有する前に tidy_project() による移行が必要で、ユーザーは多くの場合、記憶を頼りに PROJECT.md を再構築することを望みません。

既存の散在したコードについて: community-publish スキル → tidy_project(any_dir) を呼び出して、公開前に再編成します。

---

API コストとレート制限: すべての外部 API 呼び出しは sc-proxy を経由し、リクエストごとに課金され、レート制限が適用されます。 設計する前に、config/context/references/sc-proxy.md を読んで、料金表と制限を確認してください。

• コストを見積もる: credits_per_request × requests_per_run × runs_per_day × 30
• レート制限を守る: たとえば CoinGecko は 60 req/min — 1 分ごとに 10 コインをポーリングするタスクは問題ありませんが、100 コインは問題ありません
• N 回の個別呼び出しよりもバッチエンドポイントを優先する（例: 複数の id を指定した coin_price と、N 回の個別呼び出し）
• 純粋なスクリプトタスク（API なし）: 約 0 credits/run
• LLM コストの警告: ハイエンドモデルは 1 回の呼び出しで $0.10 を超えることがあります。料金はモデル層によって劇的に異なり、高価なモデルは同じワークフローで budget モデルの 100 倍以上のコストになることがあります。
• モデル別の見積もりが必須: LLM コストは単一の汎用的な数値を使うのではなく、モデル別に分解してください（model_price_per_call × expected_calls_per_run × runs_per_day × 30）。
• ダッシュボードの自動更新は credits を消費します — ユーザーが別途希望しない限り、手動更新をデフォルトにしてください
• 支出保護: 予測される月間 LLM コストが高い場合は、実装前に呼び出し元ごとの制限を適用するかどうかを明示的に確認してください。
• 呼び出し元ごとの追跡（必須）: プロキシ経由のすべてのリクエストには SC-CALLER-ID（例: job:{JOB_ID}、preview:{preview_id}、chat:{thread_id}）を含めて、使用量を追跡し上限を設定できるようにする必要があります。詳細は config/context/references/sc-proxy.md § Caller Credit Limit を参照してください

データの信頼性: ネイティブツール > プロキシ経由の API > 直接リクエスト > Web スクレイピング > LLM の数値（決して使用しない）。 鉄則: スクリプトがデータを取得する。LLM はテキストを分析する。最終出力 = スクリプトの変数 + LLM の文章。

タスクスクリプトはスキル関数を直接インポートできます:

from core.skill_tools import coingecko, coinglass  # auto-discovers skills/*/exports.py
prices = coingecko.coin_price(coin_ids=["bitcoin"], timestamps=["now"])

ツール名 = SKILL.md の frontmatter にある tools: リスト。build-patterns.md § Using Skill Functions を参照してください。

---

フェーズ 2: BUILD

すべての成果物はこのサイクルに従います:

Build one small piece → Run it → Verify output → ✅ Next piece / ❌ Fix first

構築物	検証方法	合格基準
データフェッチャー	実行し、生のレスポンスを出力	空でない、最新、妥当
API エンドポイント	curl localhost:{port}/api/...	正しい JSON
HTML ページ	preview_serve + preview_check	ok = true
タスクスクリプト	python3 tasks/{id}/run.py	数値がソースと一致
LLM 分析	LLM のテキストではなく、スクリプト変数からの数値	テンプレートパターンを使用

検証のレイヤリング:

• Critical(プレビュー/有効化の前に必ず合格): データの正確性、コアロジック、クラッシュしないこと
• Informational(納品後に修正可能): スタイリング、エッジケースのメッセージ、軽微な UX の改善

アンチパターン:

• ❌ 何も実行せずに「完了!」
• ❌ 200 行以上書いてから初めてテストする
• ❌ 「動くはず」

→ 詳細なパターン: references/build-patterns.md を読む

コードの実践

• edit_file の前に read_file — 何があるかを理解する
• 修正には write_file よりも edit_file
• write_file の前に ls を確認 — 既存ファイルの重複を避ける
• 大きなファイル(300 行超): 複数のファイルに分割するか、スケルトンを先に作って bash で注入
• 環境変数: os.environ["KEY"]、インストールは setup.sh に永続化

ダッシュボード UX のデフォルト(type=preview)

適切なデフォルトを自分で判断し、初回ロード時に実際のデータをレンダリングしてください。フィルターはユーザーが後で調整できる任意の絞り込みとして扱い、初期表示を制限する前提条件にはしないでください。適切な間隔で自動更新してください。何かが表示される前に「クリックして読み込む」/「アドレスを入力」/「銘柄を選択」を求めてはいけません。

ビジュアルデザインの品質(すべての HTML 出力で必須): ui-design スキルがインストールされている場合、HTML/CSS を書く前に必ずその SKILL.md を read_file で読み、従ってください。project-builder はエンジニアリングのワークフローを担い、ui-design はビジュアルの品質を担います。project-builder だけを使うと、機能的だがビジュアルが汎用的な出力になります。

---

プラットフォームのルール

• エージェントツールはツール呼び出し専用です — スクリプトにインポートすることはできません
• プレビューのパスは相対パスである必要があります（/path ではなく ./path）
• プレビューのポートはコードにハードコードし、環境変数から読み取らないでください。 各プレビューはそれぞれ独自の Pod で実行され、環境変数によるポートの取り決めは Pod 間で信頼できません。任意の空きポート（例: 8765）を選び、アプリに直接書き込み、同じ番号を preview(action="serve", port=...) に渡してください。この 2 つは完全に一致している必要があります。
• 同時実行するプレビューには異なる ID が必要です。 2 つのプレビューが同じ dir を共有している場合、新しい方が古い方を自動的に強制終了します（同一ディレクトリ置き換えルール）。プレビュー ID はディレクトリに紐付けられるようになりました。同じ dir を再配信しても、タイトルが変わっても同じ ID が維持されるため、以前に共有された /preview/{id}/ リンクは有効なままです。再配信後は、必ず /preview/{id}/ リンクをユーザーに再送信してください。新しい ID を期待して新しいタイトルを付けたり、ID の変種を推測したりしないでください。
• フルスタック = 1 ポート（バックエンドが API + 静的ファイルを配信）
• Cron の時刻は UTC です — ユーザーのタイムゾーンから変換してください
• プレビューの配信と公開 → プラットフォームリファレンス config/context/references/preview-guide.md を参照
• localhost API → config/context/references/localhost-api.md を参照
  • タスクスクリプトは、いつエージェントを呼び出すか、どのデータ・コンテキストを渡すか、どのモデルを使うかを決定します
  • パターン: スクリプトがデータを取得 → 注目に値するか評価 → 必要なときだけ LLM を呼び出す → 結果を出力
• スクリプト内の LLM — 2 つの選択肢（詳細は references/build-patterns.md）:
  • OpenRouter（sc-proxy 経由）: 軽量で、テキストの要約・翻訳・整形に適しています。直接 API を呼び出し、エージェントのオーバーヘッドはありません。
  • localhost /chat/stream: ツールを備えたフルエージェント。LLM がツールアクセスを必要とする場合にのみ使用してください。
• データテンプレートのルール: 数値はスクリプトが所有し、言葉は LLM が所有します。最終出力は、スクリプト変数のデータ + LLM の分析を組み立てたものです。ユーザーが見る数値の唯一の情報源を LLM の出力にしてはなりません。
• API のコストとレート制限 → プラットフォームリファレンス config/context/references/sc-proxy.md を参照
• 収益化（任意）: 構築した任意の HTTP サービスは、x402 スキルを使って 有料サービスに変えることができます — 変更されていないアプリの前段に置くリバースプロキシ ゲートウェイが、呼び出しごと / サブスクリプション（週次〜年次）/ 買い切り / プリペイド残高に応じて Base 上の USDC を課金し、マルチプランを サポートします。ユーザーがプロジェクトの課金、API アクセスの販売、エージェント間 決済について言及した場合は、ビルドフェーズ後に skills/x402/SKILL.md を読み、 scripts/monetize.py でサービスをラップしてください（GATEWAY ポートを公開し、 アップストリームは公開しないでください）。 ラップ後の完全な有料サービスチェーン: ゲートウェイを preview(serve) → community-publish → publish_preview()（公開 URL）→ create_paid_service(..., pricing_options=[...]) → submit_for_review() （マルチプランサービス: レビューは X-Pricing-Model ヘッダーを介して 各プランの 402 金額を検査します） → publish_service() → Service Marketplace で公開。詳細: community-publish SKILL.md § 有料サービスの 掲載。
• 常時稼働サービス（長時間実行 / 公開済み / 有料）: エージェントマシンは アイドル時に自動サスペンドし、自動更新の再起動がサービスプロセスを 強制終了します。24 時間 365 日到達可能であり続ける必要があるサービスには、 ① キープアライブ監視（サービスを再起動するスケジュールタスク — skills/x402/SKILL.md の「常時稼働の可用性」を参照）、② マシンを MANUAL 更新モードに 切り替える（Web ダッシュボードのトグル。エージェントはマシン内でモードを 読み取ることしかできません — 「auto」と読み取った場合は、ユーザーに スイッチを切り替えるよう促してください。そうしないと、次のプラットフォーム 更新でサービスが停止します）が必要です。

---

フェーズ 3: デバッグ

CHECK LOGS → REPRODUCE → ISOLATE → DIAGNOSE → FIX → VERIFY → REGRESS

• まずログを確認します — タスクログ、プレビューの診断情報、stderr を確認してください。ログから明確な原因が判明した場合は、修正へ進んでください。
• ログが不十分な場合にのみ再現します — 失敗を自分の目で確認してください
• どのレイヤーが壊れているかを特定します（データ? ロジック? LLM? 出力? フロントエンド? バックエンド?）
• 根本原因を修正し、同じ再現手順で検証します。ただ修正するのではなく、修正して確認してください。

スリーストライクルール: 同じアプローチが2回失敗したら → 停止 → 考え直す → ユーザーに説明する → 別のアプローチを取る。

→ 詳細なデバッグ手順: references/debug-handbook.md を読む

---

クイックチェックリスト

キックオフ: ☐ 意図を明確化した ☐ アーキテクチャを提案した ☐ コストを見積もった ☐ ユーザーが確認した（フェーズ 2 の前に必須）

ビルド: ☐ 各コンポーネントをテストした ☐ 数値がソースと一致する ☐ エラーを処理した ☐ プレビューが正常（Web）

デバッグ: ☐ ログを確認した ☐ 再現した（またはスキップ — ログで十分） ☐ レイヤーを特定した ☐ 根本原因を発見した ☐ 修正を検証した ☐ リグレッションを確認した