Getting Started

Language: English | 日本語 Last updated: 2026-05-31 (updated 2026-05-31: /getting-started/ の HTTP 500 復旧のため CF Pages アセットを強制リハッシュ, #156; 2026-05-28: 既存プロジェクト向けクイックスタート + —user ガイド追加, #130 PR-3) EN canonical: 2026-05-31 (updated 2026-05-31) of wiki/en/Getting-Started.md Audience: 新規ユーザー

このページはAphelionを使い始めるために必要なすべてをカバーします：Claude Code のセットアップ、初回実行のウォークスルー、利用シナリオ、コマンドリファレンス、トラブルシューティング。

目次

• 前提条件
• クイックスタート
• 既存プロジェクト向けクイックスタート
• 初回実行ウォークスルー
• 利用シナリオ
• コマンドリファレンス
• 典型的なセッションの進み方
• トラブルシューティング
• 関連ページ
• 正規ソース

---

前提条件

必要条件	詳細
Claude Code	Claude Code CLIのインストールと認証

npx github:kirin0198/aphelion-agents init でインストールすることもできます（クローン不要）。または、リポジトリを手動でクローンする方法もあります：

git clone https://github.com/kirin0198/aphelion-agents.git

---

クイックスタート

npx でインストール（推奨）

クローン不要で最も手早く始められる方法です：

# プロジェクトに初回配置
npx github:kirin0198/aphelion-agents init

# ユーザーホーム (~/.claude/) に配置
npx github:kirin0198/aphelion-agents init --user

# 最新版に更新
npx github:kirin0198/aphelion-agents update
npx github:kirin0198/aphelion-agents update --user

キャッシュに関する注意: npx は name@version でパッケージをキャッシュします。同じバージョン文字列の古いキャッシュがローカルに残っている場合、update はその古いスナップショットを無言でコピーします。強制的に最新を取得するには: ref を main に固定する (npx github:kirin0198/aphelion-agents#main update) か、キャッシュをクリアして (npm cache clean --force) 再実行してください。 実行時に表示される source: aphelion-agents@<version> を main の package.json の version と突き合わせると確実に最新が反映されたか確認できます。

init vs init --user: どちらを使うべきか？

ケース	推奨
特定プロジェクトで使う	init（プロジェクトローカル）
複数プロジェクトで共通利用	init --user（グローバル）
project-rules.md を使う	必ずプロジェクトローカル

注意: project-rules.md はプロジェクトの .claude/rules/ ディレクトリに配置する必要があります（プロジェクトローカル）。 init --user でグローバルにインストールした場合でも、project-rules.md は各プロジェクトで /aphelion-init を実行して生成してください。 ~/.claude/rules/ にグローバルで project-rules.md を置くと、無関係なプロジェクトにも影響が及ぶ可能性があります。

git clone でインストール（代替手順）

リポジトリをクローンしてから手動でファイルをコピーする方法：

.claude/ ディレクトリをプロジェクトにコピーしてClaude Codeを起動：

cp -r .claude /path/to/your-project/
cd /path/to/your-project && claude

/aphelion-init
/discovery-flow TODOアプリを作りたい

---

既存プロジェクト向けクイックスタート

既存のコードベースに Aphelion を導入する手順です：

ステップ1: Aphelion をインストール

npx github:kirin0198/aphelion-agents init
# または: cp -r /path/to/aphelion-agents/.claude /path/to/your-project/

ステップ2: プロジェクト固有ルールのセットアップ

/aphelion-init

rules-designer がプロジェクトの .claude/rules/project-rules.md を生成します。フローを実行する前に必ず行ってください。

ステップ3: ドキュメントの生成（SPEC.md / ARCHITECTURE.md がない場合のみ）

/codebase-analyzer このプロジェクトを分析してSPEC.mdとARCHITECTURE.mdを生成してください

プロジェクトに既に SPEC.md と ARCHITECTURE.md がある場合はこのステップをスキップしてください。

ステップ4: 作業を開始

/analyst {issueや機能の説明}
# または
/maintenance-flow {トリガーの説明}

単一 issue のワークフローには /analyst、Patch / Minor / Major の自動トリアージが必要な場合は /maintenance-flow を使用してください。

判断フローチャート:

プロジェクトに SPEC.md と ARCHITECTURE.md がありますか？
|
+-- YES --> /analyst  または  /maintenance-flow
|
+-- NO  --> /codebase-analyzer  -->  /analyst  または  /maintenance-flow

---

初回実行ウォークスルー

このウォークスルーは新規プロジェクトでClaude Codeを使用します。

ステップ1：Aphelionをプロジェクトにコピー

cp -r /path/to/aphelion-agents/.claude /path/to/your-project/
cd /path/to/your-project
claude

ステップ2：プロジェクト固有ルールのセットアップ（必須）

/aphelion-init

rules-designer が言語 / フレームワーク、Git 慣行、ビルドコマンド、出力言語、Co-Authored-By ポリシーを対話で確認し、.claude/rules/project-rules.md に書き込みます。以降のすべてのエージェントはこのファイルが存在することを前提にプロジェクトコンテキストを読み取ります。提供されているコマンドの一覧が必要な場合は /aphelion-help をいつでも実行できます。

ステップ3：Discoveryを開始

/discovery-flow ユーザー認証付きのタスク管理Webアプリを作りたい

Flow Orchestrator（フローオーケストレーター）がプランを決定するためにいくつかのトリアージ質問をします。認証付き Web アプリの場合、Standard または Full が選択されます。

ステップ4：Discovery出力のレビュー

すべてのDiscoveryフェーズが完了したら、DISCOVERY_RESULT.md をレビューします。満足したらDeliveryに進みます。

ステップ5：Deliveryを開始

/delivery-flow

Flow Orchestrator が DISCOVERY_RESULT.md を読み込み、実装フェーズのトリアージを再度行います。

ステップ6：レビューと反復

各フェーズ後、Flow Orchestrator が生成物を表示して承認を求めます。承認・修正依頼・停止を選択できます。

ステップ7：Operationsを開始（serviceのみ）

/operations-flow

PRODUCT_TYPE: service の場合のみ必要です。Dockerfile・CI/CD・運用計画を構築します。

---

利用シナリオ

シナリオ1：新規プロジェクト（フルフロー）

ゼロから要件探索 → 設計・実装 → デプロイまで一貫して行う：

/discovery-flow ブログ管理システムを作りたい

Discoveryが完了し DISCOVERY_RESULT.md をレビューした後：

/delivery-flow

Deliveryが完了した後（serviceプロジェクトの場合）：

/operations-flow

シナリオ2：サクッと作りたい（Deliveryのみ）

何を作るかが既に決まっている場合：

/delivery-flow 連絡先管理のREST APIを作りたい

DISCOVERY_RESULT.md がないため、Flow Orchestrator が直接インタビューします。

シナリオ3：既存プロジェクトへの変更（ドキュメントあり）

プロジェクトに SPEC.md と ARCHITECTURE.md がある場合：

/analyst メールアドレスに特殊文字が含まれるとログインエンドポイントで500エラーが発生する

analyst がGitHub issueとアプローチ文書を生成した後：

/delivery-flow

フローはPhase 3（アーキテクチャ）から合流し、仕様・UIデザインをスキップします。

シナリオ3b：Maintenance フロー (バグ / CVE / 小機能のトリアージ付き)

変更が小さくトリアージを自動化したい場合:

/maintenance-flow メールアドレスに特殊文字が含まれるとログインエンドポイントで 500 エラーが発生する

change-classifier がトリガーを分析して Patch / Minor / Major を提案します。Patch / Minor は単独で完結、Major は MAINTENANCE_RESULT.md 経由で /delivery-flow へ自動引き渡しされます。

/maintenance-flow を /analyst よりも優先する判断基準:

• 変更に緊急性がある (P1/P2 インシデント)
• 影響範囲の自動分析 (ファイル・依存関係・リグレッションリスク) を得たい
• 単一 issue ワークフローではなくガイド付きプラン選択が欲しい

シナリオ4：既存プロジェクトへの変更（ドキュメントなし）

詳細な4ステップのガイド（/codebase-analyzer を実行するタイミング、/analyst または /maintenance-flow への進め方を含む）は 既存プロジェクト向けクイックスタート を参照してください。

シナリオ5：スタンドアロンエージェント

フローなしで任意のエージェントを直接起動できます：

/security-auditor  （既存コードにセキュリティ監査を実行）
/reviewer          （コードレビューのみ実行）
/doc-writer        （READMEとCHANGELOGを生成）

---

コマンドリファレンス

コマンド	用途	入口
/aphelion-init	初回プロジェクトルール設定（rules-designer を起動）	npx aphelion-agents init 直後
/aphelion-help	Aphelion のスラッシュコマンド一覧を表示	任意のプロジェクトで随時
/aphelion-check	ヘルスチェック: agents / rules / hooks / gh auth / git / Docker を検証	任意のプロジェクトで随時
/discovery-flow {説明}	要件探索を開始	新規プロジェクト
/delivery-flow	設計・実装を開始	Discovery後、または既存SPEC.mdがある場合
/operations-flow	デプロイ・運用を開始	Delivery後、serviceタイプのみ
/doc-flow	顧客向け成果物を生成（HLD / LLD / API リファレンス / 運用マニュアル / ユーザーマニュアル / 引継ぎ資料）	SPEC.md + ARCHITECTURE.md があるプロジェクト
/analyst {issue}	既存プロジェクトのバグ・機能を分析	SPEC.mdがあるプロジェクト
/maintenance-flow {トリガー}	既存プロジェクトの保守トリアージと実行 (Patch/Minor/Major)	SPEC.md + ARCHITECTURE.md があるプロジェクト
/codebase-analyzer {指示}	既存コードから仕様を逆生成	SPEC.mdがないプロジェクト
/reviewer	SPEC.md と ARCHITECTURE.md に基づくコードレビュー	SPEC.mdがあるプロジェクト
/tester	TEST_PLAN.md に基づいてテストを実行または生成	TEST_PLAN.mdがあるプロジェクト
/rules-designer	.claude/rules/project-rules.md を対話的に生成・更新	任意のプロジェクト
/secrets-scan	リポジトリ内のハードコードされたシークレットを grep で検出	任意のプロジェクト
/vuln-scan	依存関係の脆弱性スキャン（技術スタックを自動検出）	任意のプロジェクト

これらのコマンドは .claude/commands/*.md でスラッシュコマンドとして定義されています（Claude Code）。 常に最新の一覧は /aphelion-help で確認できます。

---

典型的なセッションの進み方

トリアージ質問

フロー開始時、Flow Orchestrator がプロジェクトについて 4〜6 問質問します。なるべく正確に答えてください — これがどのエージェントを実行するかを決定します。

フェーズ承認

各エージェント完了後、Flow Orchestrator がサマリーを表示して以下を尋ねます：

• 承認して続行 — 次のフェーズへ進む
• 修正を依頼 — 変更を説明してエージェントが再実行される
• 停止 — フローを終了

成果物ファイル

各エージェントは1つ以上のファイルを生成します：

フェーズ	生成されるファイル
Discovery	INTERVIEW_RESULT.md、RESEARCH_RESULT.md、POC_RESULT.md、SCOPE_PLAN.md、DISCOVERY_RESULT.md
Delivery	SPEC.md、UI_SPEC.md、ARCHITECTURE.md、TASK.md、実装コード、TEST_PLAN.md、SECURITY_AUDIT.md、README.md
Operations	Dockerfile、docker-compose.yml、.github/workflows/ci.yml、DB_OPS.md、OBSERVABILITY.md、OPS_PLAN.md

TASK.md について: TASK.md は3つの状態を持つライフサイクルに従います：

1. フェーズ開始時 — developer が ARCHITECTURE.md のタスクチェックリストを 元に TASK.md を生成します。
2. フェーズ実行中 — developer が各タスク完了後にチェックボックスをチェック済みにし、 「Recent Commits」セクションを更新します。
3. フェーズ完了時 — developer が TASK.md を空のプレースホルダーにリセットして、 次のフェーズがクリーンな状態で開始できるようにします。チェック済みの TASK.md が main にコミットされている場合はルール違反です（.claude/rules/document-versioning.md §“TASK.md Lifecycle” 参照）。フェーズの分析と成果は docs/design-notes/<slug>.md に記録します。

リポジトリルートの空の TASK.md は正常なアイドル状態であり、未完了の作業があることを示すものではありません。

セッション再開

セッションが中断された場合（特に developer の途中）、再開できます：

/developer  （TASK.mdから再開）

またはフロー全体を再起動してください — 既存のファイルを検出して続きから始めるか最初からやり直すかを尋ねます。

---

トラブルシューティング

「DISCOVERY_RESULT.md に必須フィールドがありません」

Delivery Flowは起動時に DISCOVERY_RESULT.md を検証します。必須フィールド（PRODUCT_TYPE、「プロジェクト概要」、「要件サマリー」）が不足していると報告された場合、ファイルを編集して不足セクションを追加し、/delivery-flow を再実行してください。

「エージェントがSTATUS: errorを返しました」

Flow Orchestrator がオプションを表示します：

• 再実行 — 同じエージェントを再実行
• 修正して再実行 — 修正内容を説明してから再実行
• スキップ — このエージェントをスキップして続行
• 停止 — フローを中断

「developerが止まっている / 時間がかかりすぎている」

developer は TASK.md を使用して進捗を追跡します。タスクに時間がかかりすぎる場合は中断して後で再開できます。次の実行では TASK.md の最初の未完了タスクから開始します。

---

関連ページ

• Architecture: Domain Model
• Triage System

正規ソース

• README.ja.md — プロジェクト概要とクイックスタート
• .claude/commands/ — スラッシュコマンド定義
• .claude/agents/discovery-flow.md — Discovery フロー起動手順
• .claude/agents/delivery-flow.md — Delivery フロー起動手順