Autonomous Engineer

日本語

English

日本語

English

Appearance

アーキテクチャ ​

概要 ​

Autonomous EngineerはAI駆動のソフトウェア開発ワークフローを調整するモジュラーシステムとして設計されています。

アーキテクチャは以下を重視しています：

  • モジュール性
  • 明確な境界
  • 拡張性
  • 最小限の結合
  • プロバイダー抽象化

システムはクリーンアーキテクチャとヘキサゴナルアーキテクチャに影響を受けた原則に従い、コアロジックが外部ツールやプロバイダーから独立して維持されます。

これにより、システムは大規模なアーキテクチャの書き直しなしに進化できます。

アーキテクチャ原則 ​

アーキテクチャはいくつかの基本原則に従っています。

関心の分離 ​

各モジュールは明確に定義された責務を持つべきです。

例：

  • ワークフロー調整
  • 仕様生成
  • タスク実行
  • AI連携
  • リポジトリ管理

モジュールはドメイン外の責務を持つべきではありません。

依存性の逆転 ​

コアシステムロジックはインフラストラクチャの実装に直接依存してはなりません。

代わりに、依存関係はインターフェースとして定義され、アダプターによって実装されるべきです。

例：

コアロジック
↓
インターフェース
↓
アダプター
↓
外部システム

外部システムには以下が含まれます：

  • AIプロバイダー
  • Gitリポジトリ
  • SDDフレームワーク
  • ファイルシステム

交換可能なインフラストラクチャ ​

インフラストラクチャコンポーネントはコアロジックを変更せずに交換可能であるべきです。

例：

  • 異なるLLMプロバイダー
  • 異なる仕様システム
  • 異なるメモリバックエンド

最小コンテキストサーフェス ​

AIとのやり取りは最小限の必要なコンテキストのみを受け取るべきです。

これにより推論品質が向上し、トークン消費量が削減されます。

クリーンアーキテクチャ ​

システムはいくつかのレイヤーに整理されています。

@include: ../../_partials/clean-architecture-diagram-ja.md

main/ — エントリポイントとトップレベルDIコンテナ ​

main/ はクリーンアーキテクチャのレイヤーの外側に位置します。バイナリのエントリポイントであり、main/di/ ファクトリーを呼び出して完全な依存グラフを組み立てる唯一のモジュールです。以下を含みます：

  • index.ts — プロセスエントリポイント；CLIアダプターに委譲する
  • run-container.ts / configure-container.ts — 遅延初期化された依存関係を持つDIコンテナクラス

他のモジュールは main/ をインポートしません。

main/di/ — サブシステムDIファクトリー ​

main/di/ には、各サブシステム（実装ループ、Git統合、安全実行器など）の具体的なサービスとインフラオブジェクトをインスタンス化して配線するファクトリー関数とDIコンテナが含まれます。各ファクトリーは application/services と infra/* のコンストラクターを呼び出し、ポートインターフェースを返します。main/di/ は main/ からのみ呼び出されます — 他のモジュールはインポートしません。

依存性の逆転と「infra → ports が循環参照でない」理由 ​

infra/*（bootstrap以外）が application/ports をインポートするのは、何を実装すべきかを知るためです。application は infra をインポートしません。依存関係は厳密に一方向です：

コンパイル時：  usecase → ports ← infra   （どちらもports に依存。互いには依存しない）
実行時（DI）：  usecase → [ポート] → infra実装   （main/が両者を接続する）

main/ のみが両側を知っており、依存性注入の配線を行います。これが依存性逆転の原則です：高レベルポリシー（usecases）と低レベル詳細（infra）の両方が抽象（ports）に依存し、互いには依存しません。

レイヤー依存ルール ​

@include: ../../_partials/src-dependency-direction-ja.md

アプリケーションレイヤー：Usecases と Services の違い ​

application/ レイヤーには2つの異なるサブレイヤーがあります：

サブレイヤー役割例
usecases/特定のユーザー操作に対する薄いエントリポイントオーケストレーターRunSpecUseCase
services/複数のユースケースを横断して再利用される調整ロジック。アプリケーションレベルのポリシーを持つが、ドメインルールではないAgentLoopService、ToolExecutor、SafetyGuardedToolExecutor、ContextEngineService

サービスには、単一のユースケースクラスには複雑すぎるが、ドメイン（ポート抽象に依存するためドメインロジックではない）にも属さないロジックが含まれます。サービスはポートとドメインに依存でき、ユースケースはサービスとポートに依存できます。

ユースケースレイヤー ​

ユースケースレイヤーは、アプリケーション固有のビジネスルールをコードで表現し、開発ワークフローを調整します。

このシステムでは、ワークフローオーケストレーション（spec-init → requirements → design → tasks → implementation といったフェーズを駆動すること）はユースケースの責務です。UIやフレームワーク・外部システムに依存せず、ドメインエンティティを調整してアプリケーションの目標を実現します。

責務：

  • 開発ライフサイクルのフェーズを調整する
  • ドメインエンティティを調整して、単一のアプリケーション目標を実現する
  • 各ユースケース固有のビジネス制約を強制する
  • UI・フレームワーク・外部システムから独立した状態を維持する

例：

  • RunSpecUseCase — 仕様初期化から実装までのフルワークフローを主導する

ユースケースはコードレベルではポートインターフェースとアプリケーションサービスのみに依存し、アダプターやインフラストラクチャのパッケージを直接インポートすることはありません。実行時には、main/ による依存性注入（DI）によって具体的なインフラストラクチャ実装が注入されます。

コアモジュール ​

ドメインレイヤーにはコアシステムモジュールが含まれます。

ワークフローエンジン ​

開発ライフサイクルの調整を担当します。

主な責務：

  • フェーズ遷移
  • 実行調整
  • ワークフロー状態管理

フェーズ例：

spec-init
requirements
design
validate-design
tasks
implementation
pull-request

ワークフローエンジンはステートマシンとして動作します。

仕様エンジン ​

仕様フレームワークとのやり取りを処理します。

責務：

  • 仕様の初期化
  • 要件の生成
  • 設計の作成
  • 設計の検証
  • タスクの生成

仕様エンジンはどの特定のフレームワークにも直接依存しません。

実装エンジン ​

生成されたタスクの実行を担当します。

各タスクは反復ループを通じて処理されます。

実装
↓
レビュー
↓
改善
↓
コミット

このループはタスクが品質条件を満たすまで継続されます。

レビューエンジン ​

ワークフロー中に生成されたアーティファクトを評価します。

例：

  • 設計検証
  • コードレビュー
  • アーキテクチャ一貫性チェック
  • 要件コンプライアンス

レビューエンジンは出力が仕様と整合していることを確保します。

自己修復エンジン ​

AI実行が失敗または非効率になる場合を分析します。

責務：

  • 失敗分析
  • 欠けているルールの特定
  • システム知識の更新

出力には以下のファイルの更新が含まれる場合があります：

rules/
implementation_rules.md
review_rules.md
debugging_patterns.md

これにより長期的なシステム改善が可能になります。

アダプターパターン ​

外部統合はアダプターを使用して実装されます。

アダプターはコアシステム操作をプロバイダー固有の実装に変換します。

構造例：

SpecEngine インターフェース

├── CCSddAdapter
├── OpenSpecAdapter
└── SpecKitAdapter

AIプロバイダーも同様：

LLMProvider インターフェース

├── ClaudeProvider
├── CodexProvider
├── CursorProvider
└── CopilotProvider

これにより、コアシステムが外部技術から独立した状態を維持します。

ワークフローアーキテクチャ ​

ワークフローは決定論的でフェーズベースです。

ワークフロー例：

SPEC_INIT
↓
REQUIREMENTS
↓
DESIGN
↓
VALIDATE_DESIGN
↓
TASK_GENERATION
↓
IMPLEMENTATION
↓
PULL_REQUEST

各フェーズは特定のエンジンを呼び出します。

マッピング例：

SPEC_INIT → 仕様エンジン
REQUIREMENTS → 仕様エンジン
DESIGN → 仕様エンジン
TASKS → 仕様エンジン
IMPLEMENTATION → 実装エンジン
REVIEW → レビューエンジン

ワークフローエンジンは遷移を制御し、正しい順序を確保します。

メモリアーキテクチャの統合 ​

システムは学習とコンテキスト再利用のために永続的メモリを統合します。

メモリはいくつかのレイヤーに分かれています。

短期メモリ ​

単一のワークフロー実行中に使用されます。

例：

  • 現在の仕様
  • 現在のタスク
  • 設計アーティファクト

プロジェクトメモリ ​

リポジトリ固有の知識。

例：

  • コーディング規約
  • アーキテクチャパターン
  • レビューフィードバック

知識メモリ ​

開発中に発見された再利用可能なパターン。

例：

  • デバッグ戦略
  • 実装テンプレート
  • ルールの改善

メモリにより、システムが時間とともに進化できます。

LLM統合 ​

AIモデルはLLMプロバイダーインターフェースを通じてアクセスされます。

プロバイダー抽象化は以下を管理します：

  • プロンプト実行
  • レスポンス解析
  • コンテキスト制御
  • プロバイダー固有のAPI

インターフェース例：

LLMProvider

complete(prompt)
clearContext()

この設計により、コアロジックを変更せずに異なるAIシステムを使用できます。

コンテキスト管理 ​

効果的なコンテキスト管理はLLMの信頼性にとって重要です。

システムはいくつかの戦略を強制します。

フェーズ分離 ​

新しいワークフローフェーズに入るときにコンテキストがリセットされます。

タスク分離 ​

各タスクセクションは最小限のコンテキストで実行されます。

アーティファクト注入 ​

プロンプトには関連するドキュメントのみが含まれます。

例：

  • 仕様ドキュメント
  • 設計ドキュメント
  • 関連するソースファイル

これらの戦略はトークン消費を最小化し、推論エラーを削減します。

Git統合 ​

Git操作は専用のコントローラーを通じて実行されます。

責務：

  • ブランチ作成
  • 変更のコミット
  • 更新のプッシュ
  • プルリクエスト作成

自動化されたフロー例：

フィーチャーブランチ作成
タスク実装
変更のコミット
ブランチのプッシュ
プルリクエスト作成

これにより、エンドツーエンドの自動化開発ワークフローが可能になります。

Rust統合 ​

一部のコンポーネントはJavaScript環境が提供するよりも高いパフォーマンスを必要とする場合があります。

Rustは以下に使用される可能性があります：

  • メモリインデックス作成
  • セマンティック検索
  • コンテキスト差分
  • 知識取得

Rustモジュールは以下を使用して統合できます：

  • napi-rs
  • WebAssembly

アーキテクチャ例：

TypeScriptコア
│
▼
Rustメモリエンジン

これにより、パフォーマンスクリティカルな操作を効率的にスケールできます。

拡張性 ​

アーキテクチャは長期的な拡張性のために設計されています。

将来の拡張には以下が含まれる可能性があります：

マルチエージェントシステム ​

異なるタスクを専門とする異なるエージェント。

例：

  • プランニングエージェント
  • アーキテクチャエージェント
  • 実装エージェント
  • レビューエージェント

高度なメモリシステム ​

将来のバージョンには以下が含まれる可能性があります：

  • ベクターデータベース
  • セマンティック知識グラフ
  • 自動パターン抽出

ワークフローバリアント ​

異なる開発方法論がサポートされる可能性があります。

例：

  • テスト駆動ワークフロー
  • リサーチワークフロー
  • インフラストラクチャ自動化

ディレクトリ構造 ​

プロジェクトは実装境界によって整理されたモジュラーなディレクトリ構造に従っています。

命名規則 ​

実装ディレクトリは <責務>-<言語サフィックス> の形式で命名されます：

  • プレフィックスはそのコンポーネントのドメイン上の責務を示す
  • サフィックスは実装言語を示す（-ts、-rs、-rb など）

この規則により、意味的な役割を言語名に埋没させることなく、開発者とAIエージェントの両方に対して技術的な境界を明示できます。

例：

  • orchestrator-ts/ — TypeScriptで実装されたワークフローオーケストレーションエンジン
  • memory-rs/ — 将来Rustで実装予定のメモリインデックス/検索コンポーネント

現在の構造 ​

トップレベルのプロジェクト構成：

autonomous-engineer/
├─ orchestrator-ts/          # ワークフローオーケストレーションエンジン + aes CLI（TypeScript/Bun）
│  ├─ src/                   # プロダクションソース — 詳細は下記を参照
│  ├─ tests/
│  ├─ package.json
│  └─ tsconfig.json
│
├─ docs/
│  ├─ architecture/
│  ├─ agent/
│  ├─ workflow/
│  ├─ memory/
│  └─ development/
│
├─ .kiro/
│  ├─ specs/
│  └─ steering/
│
└─ README.md

orchestrator-ts/src/ のレイアウト ​

@include: ../../_partials/src-directory-structure-ja.md

構造の哲学 ​

各実装ディレクトリ（*-ts、*-rs など）は、独自のツールチェーン、依存関係、内部アーキテクチャを持つ自己完結したコンポーネントです。orchestrator-ts/src/ 内では、ディレクトリ構造がクリーンアーキテクチャのレイヤーに直接対応します：

  • main/ はプロセスエントリポイントとトップレベルDIコンテナ — クリーンアーキテクチャのレイヤー外に位置し、main/di/ ファクトリーを呼び出して最終的な依存グラフを組み立てる
  • main/di/ はサブシステムDIファクトリー — 各ファクトリーが1つのサブシステムのサービスとインフラオブジェクトをインスタンス化して接続する；main/ からのみ呼び出し可能
  • adapters/cli/ は受信デリバリーアダプター — CLI引数を解析し、ユースケースを呼び出し、出力を描画する
  • application/ はアプリケーションレイヤーで、3つの関心事に分けられる：
    • usecases/ — アプリケーションビジネスルールとワークフローのオーケストレーション
    • services/ — 複数のユースケースを横断して再利用される調整ロジック
    • ports/ — アプリケーションが必要とするインターフェース定義（入出力ポート）
  • domain/ はすべての外部関心事から独立したコアドメインロジック
  • infra/ は具体的なインフラストラクチャの実装（git、LLM、ファイルシステム、ロギング等）を提供する
  • infra/utils/ はインフラサブディレクトリ間でのみ使用される共有低レベルユーティリティ
  • docs/ は開発者とAIエージェントの両方のためのアーキテクチャ知識を提供する

この構造により、コアロジックを外部依存関係から独立させながらシステムを進化させることができます。

まとめ ​

Autonomous Engineerのアーキテクチャは以下に焦点を当てています：

  • モジュラー設計
  • 厳格な境界
  • プロバイダー抽象化
  • ワークフロー決定論
  • AI調整
  • 永続的学習

このアーキテクチャにより、システムが単一のAI開発エージェントから複雑なソフトウェアシステムを管理できる完全自律エンジニアリングプラットフォームへと進化できます。

Autonomous Engineer Documentation