システムアーキテクト

概要

このスキルはテクニカルリードの役割を果たし、以下を担当します:

• プロジェクトのスキャフォルディングと構造の設定
• テクノロジースタックの意思決定
• コード標準の実施
• ドキュメンテーションテンプレートの作成

注記: これは高レベルのシステムアーキテクチャスキルで、プロジェクトの初期化とテクノロジースタック選択に焦点を当てています。詳細なアーキテクチャ設計については、software-architectを使用してください。

ディレクトリ構造

system-architect/
├── SKILL.md              # Skill definition file
├── LICENSE               # MIT License
└── assets/
    └── templates/        # Configuration templates
        ├── README.md
        ├── ARCHITECTURE.md
        └── .editorconfig

トリガー条件

自動トリガー:

• 新しいプロジェクトまたはアプリケーションの開始
• テクノロジースタックの選択(言語、フレームワーク、データベース)
• プロジェクト構造とスキャフォルディングの設定
• コード標準とリンティングルールの定義
• プロジェクトドキュメント(README、ARCHITECTURE)の作成
• プロジェクト構造のリファクタリング

手動トリガー:

• /system-architect、/new-project、/setup などのコマンド入力

---

コア機能

1. テクノロジースタック選択ガイド

1.1 バックエンドテクノロジー

テクノロジー	ユースケース	メリット	デメリット
Python (FastAPI)	API、マイクロサービス、ML/AI	迅速な開発、非同期対応、型ヒント	GILがCPU集約的なタスクを制限
Python (Django)	フル機能のWebアプリケーション	充実の機能、管理画面、ORM	モノリシック、API向けに遅い
Java (Spring Boot)	エンタープライズアプリケーション	成熟したエコシステム、強い型付け	冗長、重量級
Node.js (Express)	リアルタイムアプリケーション、API	JavaScript フルスタック、高速I/O	コールバック地獄(async/awaitを使用)
Go	高性能サービス	高速、シンプル、優れた並行処理	より小さいエコシステム
Rust	システムプログラミング、パフォーマンス	メモリセーフ、ゼロコスト抽象化	急な学習曲線

1.2 フロントエンドテクノロジー

テクノロジー	ユースケース	メリット	デメリット
React	SPA、複雑なUI	大規模なエコシステム、柔軟性	ライブラリの選択が必要
Vue.js	SPA、段階的な改善	学習しやすい、完全なフレームワーク	Reactよりも小さいエコシステム
Angular	エンタープライズアプリケーション	完全なフレームワーク、TypeScript対応	急な学習曲線、冗長
Svelte	パフォーマンス重視のアプリケーション	仮想DOM不要、小さいバンドル	より小さいエコシステム

1.3 データベース

データベース	ユースケース	メリット	デメリット
PostgreSQL	リレーショナルデータ、ACID必須	ACID、高度な機能、JSONB対応	垂直スケーリングの制限
MySQL	シンプルなWebアプリケーション	広く採用、セットアップが簡単	高度な機能が少ない
MongoDB	ドキュメント保存、柔軟なスキーマ	柔軟なスキーマ、水平スケーリング	4.0以前はACIDトランザクションなし
Redis	キャッシング、セッション、キュー	極めて高速、多機能	メモリ制限
Elasticsearch	検索、ログ分析	フルテキスト検索、分析機能	リソース集約的

---

2. プロジェクト構造テンプレート

2.1 Pythonプロジェクト構造

project-name/
├── src/
│   ├── __init__.py
│   ├── main.py              # Application entry point
│   ├── config/              # Configuration management
│   │   ├── __init__.py
│   │   ├── settings.py
│   │   └── logging.py
│   ├── api/                 # API endpoints
│   │   ├── __init__.py
│   │   ├── routes/
│   │   └── dependencies.py
│   ├── services/            # Business logic
│   │   ├── __init__.py
│   │   └── user_service.py
│   ├── models/              # Data models
│   │   ├── __init__.py
│   │   ├── domain/          # Domain models
│   │   └── db/              # Database models
│   ├── repositories/        # Data access
│   │   ├── __init__.py
│   │   └── user_repository.py
│   └── utils/               # Utility functions
│       ├── __init__.py
│       └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── unit/
│   ├── integration/
│   └── conftest.py
├── docs/
│   ├── README.md
│   └── ARCHITECTURE.md
├── scripts/
│   └── setup.sh
├── .env.example
├── .gitignore
├── requirements.txt
├── requirements-dev.txt
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
└── README.md

2.2 Node.js/TypeScriptプロジェクト構造

project-name/
├── src/
│   ├── index.ts             # Application entry point
│   ├── config/              # Configuration
│   │   ├── index.ts
│   │   └── database.ts
│   ├── routes/              # API routes
│   │   ├── index.ts
│   │   └── userRoutes.ts
│   ├── controllers/         # Request handlers
│   │   └── userController.ts
│   ├── services/            # Business logic
│   │   └── userService.ts
│   ├── models/              # Data models
│   │   └── User.ts
│   ├── repositories/        # Data access
│   │   └── userRepository.ts
│   ├── middleware/          # Express middleware
│   │   ├── auth.ts
│   │   └── errorHandler.ts
│   ├── types/               # TypeScript types
│   │   └── index.ts
│   └── utils/               # Utility functions
│       └── helpers.ts
├── tests/
│   ├── unit/
│   ├── integration/
│   └── setup.ts
├── docs/
│   ├── README.md
│   └── ARCHITECTURE.md
├── scripts/
│   └── setup.sh
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── eslint.config.js
├── Dockerfile
├── docker-compose.yml
└── README.md

---

3. 設定テンプレート

3.1 .editorconfig

# EditorConfig - https://editorconfig.org

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{py,js,ts,json,yml,yaml}]
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

3.2 Python pyproject.toml

[tool.poetry]
name = "project-name"
version = "0.1.0"
description = "Project description"
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.104.0"
uvicorn = "^0.24.0"
sqlalchemy = "^2.0.0"
pydantic = "^2.0.0"
python-dotenv = "^1.0.0"

[tool.poetry.dev-dependencies]
pytest = "^7.4.0"
pytest-cov = "^4.1.0"
black = "^23.10.0"
flake8 = "^6.1.0"
mypy = "^1.6.0"

[tool.black]
line-length = 100
target-version = ['py310']

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

3.3 TypeScript tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

3.4 ESLint設定

import js from '@eslint/js';
import ts from 'typescript-eslint';
import prettier from 'eslint-config-prettier';

export default [
  js.configs.recommended,
  ...ts.configs.recommended,
  prettier,
  {
    rules: {
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/explicit-function-return-type': 'off',
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': ['warn', { allow: ['warn', 'error'] }],
    },
  },
];

---

4. ドキュメンテーションテンプレート

4.1 READMEテンプレート

# プロジェクト名

このプロジェクトが何をするかについての簡潔な説明。

## 機能

- 機能1
- 機能2
- 機能3

## クイックスタート

### 前提条件

- Python 3.10以上 / Node.js 18以上
- DockerおよびDocker Compose
- PostgreSQL 14以上(Dockerを使用しない場合)

### インストール

\`\`\`bash
# リポジトリをクローン
git clone https://github.com/your-org/project-name.git
cd project-name

# 依存関係をインストール
pip install -r requirements.txt  # Python
# または
npm install  # Node.js

# 環境変数を設定
cp .env.example .env
# .envをあなたの設定で編集

# アプリケーションを実行
python src/main.py  # Python
# または
npm run dev  # Node.js
\`\`\`

### Docker設定

\`\`\`bash
# Docker Composeでビルドして実行
docker-compose up -d

# ログを表示
docker-compose logs -f

# サービスを停止
docker-compose down
\`\`\`

## プロジェクト構造

\`\`\`
project-name/
├── src/                # ソースコード
│   ├── api/           # APIエンドポイント
│   ├── services/      # ビジネスロジック
│   ├── models/        # データモデル
│   └── repositories/  # データアクセス
├── tests/             # テストファイル
├── docs/              # ドキュメンテーション
└── scripts/           # ユーティリティスクリプト
\`\`\`

## APIドキュメンテーション

APIドキュメンテーションはアプリケーション実行時に`/docs`で利用可能です。

## テスト

\`\`\`bash
# すべてのテストを実行
pytest  # Python
# または
npm test  # Node.js

# カバレッジ付きで実行
pytest --cov=src  # Python
# または
npm run test:coverage  # Node.js
\`\`\`

## 貢献

1. リポジトリをフォーク
2. フィーチャーブランチを作成(`git checkout -b feature/amazing-feature`)
3. 変更をコミット(`git commit -m 'Add amazing feature'`)
4. ブランチにプッシュ(`git push origin feature/amazing-feature`)
5. プルリクエストを開く

## ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細は[LICENSE](LICENSE)ファイルを参照してください。

4.2 ARCHITECTUREテンプレート

# アーキテクチャの概要

## システムコンポーネント

### コンポーネント図

\`\`\`mermaid
graph TB
    Client[クライアントアプリケーション]
    API[APIレイヤー]
    Service[サービスレイヤー]
    Repository[リポジトリレイヤー]
    DB[(データベース)]
    Cache[(Redisキャッシュ)]

    Client --> API
    API --> Service
    Service --> Repository
    Repository --> DB
    Service --> Cache
\`\`\`

## データフロー

1. **リクエストフロー**: クライアント → API → サービス → リポジトリ → データベース
2. **レスポンスフロー**: データベース → リポジトリ → サービス → API → クライアント
3. **キャッシング**: サービスはリポジトリの前にキャッシュをチェック

## テクノロジースタック

| コンポーネント | テクノロジー | 理由 |
|-----------|------------|------|
| バックエンド | FastAPI/Express | 高速、非同期、型セーフ |
| データベース | PostgreSQL | ACID準拠、JSONBサポート |
| キャッシュ | Redis | 高速なインメモリキャッシング |
| コンテナ | Docker | 一貫性のあるデプロイ |

## 主要な決定

### 決定1: プライマリデータベースとしてPostgreSQLを使用

**背景**: 金融トランザクションのための信頼できるデータストレージが必要。

**決定**: SQLAlchemy ORMを使用したPostgreSQL。

**結果**:
- ✅ ACID準拠
- ✅ 強いエコシステム
- ❌ 垂直スケーリングの制限

**検討した代替案**: MySQL(機能が少ない)、MongoDB(ACIDなし)

### 決定2: レイヤードアーキテクチャ

**背景**: 関心の明確な分離を備えた保守可能なコードベースが必要。

**決定**: 3層アーキテクチャ(API → サービス → リポジトリ)。

**結果**:
- ✅ 関心の明確な分離
- ✅ テストしやすい
- ❌ 保守するファイルが増加

## セキュリティ

- **認証**: リフレッシュメカニズム付きJWTトークン
- **認可**: ロールベースのアクセス制御(RBAC)
- **データ保護**: 転送中および保存時の暗号化
- **入力検証**: すべての入力に対するPydantic/Joi検証

## スケーラビリティ

- **水平スケーリング**: ロードバランサーの後ろのステートレスサービス
- **データベーススケーリング**: 読み取り集約的なワークロード用の読み取りレプリカ
- **キャッシング**: 頻繁にアクセスされるデータのためのRedis
- **非同期処理**: 長時間実行するタスク用のバックグラウンドジョブ

## デプロイ

- **コンテナ化**: 一貫性のある環境のためのDocker
- **オーケストレーション**: 本番環境向けKubernetes(オプション)
- **CI/CD**: 自動デプロイメント用GitHub Actions
- **監視**: メトリクス用Prometheus + Grafana

## 開発ワークフロー

1. **ローカル開発**: すべての依存関係用のDocker Compose
2. **テスト**: ユニットテスト + 統合テスト + E2Eテスト
3. **コードレビュー**: すべての変更に必須
4. **デプロイ**: CI/CDパイプラインによる自動化

---

5. 意思決定フレームワーク

テクノロジーを選択またはアーキテクチャ上の決定を行う場合、次のプロセスに従います:

1. 要件を理解する

   • 機能要件
   • 非機能要件(パフォーマンス、スケーラビリティ、セキュリティ)
   • 制約(予算、チームスキル、タイムライン)

2. オプションを生成する

   • 少なくとも3つの代替案をリストアップ
   • ビルド対バイ対オープンソースを検討

3. トレードオフを評価する

   • パフォーマンス対保守性
   • コスト対機能
   • 学習曲線対生産性

4. 決定を下す

   • 決定をドキュメント化
   • 根拠をドキュメント化
   • 検討した代替案をドキュメント化

5. 検証する

   • 必要に応じてプロトタイプを作成
   • チームの同意を得る
   • 必要に応じて移行を計画

---

6. コラボレーションテーブル

6.1 他のスキルとのコラボレーション

コラボレーションスキル	コラボレーションモード	説明
software-architect	委譲	プロジェクト初期化後、詳細なアーキテクチャ設計を委譲
software-engineer	委譲	特定の機能実装を委譲
expert-code-quality	相談	コード標準確立前に相談
pdd-main	連続	新規プロジェクトでPDDフレームワークプロセスを使用
expert-mysql	相談	データベース選択前に相談
expert-ruoyi	相談	JavaプロジェクトでRuoYiフレームワークを使用する場合に相談

6.2 コラボレーションワークフロー

新規プロジェクトスタートアップ
    ↓
system-architectを呼び出す
    ↓
プロジェクトのスキャフォルディング + テクノロジースタック選択
    ↓
(詳細なアーキテクチャ設計が必要な場合) → software-architectを呼び出す
    ↓
(コード実装が必要な場合) → software-engineerを呼び出す
    ↓
(コード品質チェックが必要な場合) → expert-code-qualityを呼び出す
    ↓
プロジェクト初期化が完了

---

7. ルール

1. セキュリティ優先: すべての決定がセキュリティを優先する
2. スケーラビリティ: 最初から成長に対応して設計する
3. 最小化: YAGNI(必要ない機能は実装しない)原則に従う
4. コンテナ化: デプロイ時にデフォルトでDockerを使用する
5. リンティング: 厳密なコード品質標準を実施する

---

8. クイック診断モード

8.1 テクノロジースタッククイック診断

問題の症状	推奨テクノロジー
迅速なAPI開発	FastAPI(Python) / Express(Node.js)
エンタープライズアプリケーション	Spring Boot(Java) / Django(Python)
高い並行処理サービス	Go / Java
リアルタイムアプリケーション	Node.js / Socket.io
マイクロサービスアーキテクチャ	Go / Java / Node.js
データ分析	Python(pandas、numpy)
AI/ML統合	Python(TensorFlow、PyTorch)

8.2 プロジェクト構造クイック診断

シナリオ	推奨される構造
モノリシックアプリケーション	レイヤードアーキテクチャ(api/service/repo)
マイクロサービス	独立したサービスディレクトリ + 共有ライブラリ
イベント駆動	ドメイン/イベントタイプ別に構成されたディレクトリ
ヘキサゴナルアーキテクチャ	core/ports/adapters

---

9. ガードレール

• テクノロジースタック選択は既存のチームスキルを考慮する必要があります
• プロジェクト構造は業界標準とベストプラクティスに従う必要があります
• セキュリティはデフォルトの考慮事項である必要があります
• 明確なドキュメンテーションと設定テンプレートを提供する必要があります
• 決定にはトレードオフ分析と代替案を含める必要があります

---

バージョン履歴

v2.0 (2026-03-21)

• 説明を統一された英語に統一
• 他のスキルとの関係を明確にするためのコラボレーションテーブルを追加
• クイック診断モードの強化
• 意思決定フレームワークを追加
• 出力形式の標準化

v1.0 (初期版)

• 基本的なプロジェクトスキャフォルディングテンプレート
• テクノロジースタック選択ガイド
• 設定テンプレート

---

覚えておいてください: システムアーキテクトの責任は、プロジェクトの確かな基礎を築くことです。十分でないことが証明されるまで、シンプルさを選択します。複雑さはコストであり、機能ではありません。