README.md
# ATLAS YAML Configuration Guide
## 概要
ATLASフレームワークをYAML形式で活用するための3つのファイル構成。
```
.atlas/
├── atlas.yaml # プロジェクト固有の設定（必須）
├── atlas-rules.yaml # ルール定義（共有）
└── atlas-catalog.yaml # 技術カタログ（共有、定期更新）
```
---
## ファイルの役割
| ファイル | 役割 | 配置場所 | 更新頻度 |
| -------------------- | -------------------------- | -------------------------- | -------------------- |
| `atlas.yaml` | プロジェクト固有の技術選定 | プロジェクトルート | プロジェクトごと |
| `atlas-rules.yaml` | アンチパターン・推奨ルール | グローバル or プロジェクト | フレームワーク更新時 |
| `atlas-catalog.yaml` | 具体的技術の特性一覧 | グローバル | 半年ごと |
---
## 使い方
### 1. 新規プロジェクト開始時
```bash
# .atlasディレクトリを作成
mkdir .atlas
# atlas.yamlをコピーして編集
cp templates/atlas.yaml .atlas/atlas.yaml
```
### 2. atlas.yamlの記入
```yaml
# 最小構成
atlas_version: "1.0"
project:
name: "My Project"
classification:
primary_archetype: A3_CONSUMER_APP
tier: T1_MVP
stack:
compute:
category: SERVERLESS_REGIONAL
selected: vercel_functions
database:
primary:
category: SERVERLESS_POSTGRES
selected: neon
```
### 3. Claude Codeでの活用
```
User: このプロジェクトの初期設定をして
Claude Code: .atlas/atlas.yamlを確認しました。
- Tier: T1_MVP
- Compute: Vercel Functions
- Database: Neon
以下の設定を行います：
1. next.config.js にNeon接続設定
2. 環境変数テンプレート作成
3. 推奨パッケージのインストール
```
---
## atlas.yaml 構造
### 必須セクション
```yaml
atlas_version: "1.0"
project:
name: "プロジェクト名"
classification:
primary_archetype: A1-A7
tier: T1-T4
stack:
compute:
category: カテゴリ名
selected: 技術名
database:
primary:
category: カテゴリ名
selected: 技術名
```
### 推奨セクション
```yaml
requirements:
scale:
expected_mau: 数値
features:
realtime: boolean
background_processing: none|light|medium|heavy
antipattern_checks:
- id: AP-XX
status: PASSED|FAILED|MITIGATED|NOT_APPLICABLE
exit_strategy:
next_tier: T2-T4
migration_triggers:
- condition: "条件"
action: "アクション"
claude_instructions:
implementation_notes:
- "注意点1"
prohibited:
- "禁止事項1"
```
---
## アーキタイプ一覧
| ID | 名称 | 用途 |
| ------------------ | ------------------ | ---------------------- |
| A1_STATIC_PRESENCE | 静的プレゼンス | コーポレート、IR、採用 |
| A2_CAMPAIGN | キャンペーン | LP、プロモーション |
| A3_CONSUMER_APP | 消費者向けアプリ | toC Webサービス |
| A4_BUSINESS_SAAS | 業務SaaS | toB システム |
| A5_MARKETPLACE | マーケットプレイス | EC、マッチング |
| A6_REALTIME | リアルタイム | チャット、コラボ |
| A7_AI_COMPUTE | AI/計算 | 生成AI、分析 |
---
## Tier一覧
| ID | 対象 | 月額予算 | チーム |
| ------------- | ---------------- | --------- | ------ |
| T1_MVP | 個人・MVP | ~$50 | 1-2人 |
| T2_STARTUP | スタートアップ | $50-500 | 2-5人 |
| T3_GROWTH | 成長期 | $500-5000 | 5-20人 |
| T4_ENTERPRISE | エンタープライズ | $5000+ | 20人+ |
---
## 技術カテゴリ一覧
### Compute
- `SERVERLESS_EDGE` - エッジ関数
- `SERVERLESS_REGIONAL` - リージョナル関数
- `CONTAINER_PAAS` - コンテナPaaS
- `SELF_HOSTED` - セルフホスト
- `KUBERNETES` - K8s
### Database
- `SERVERLESS_POSTGRES` - サーバーレスPG
- `MANAGED_POSTGRES` - マネージドPG
- `EDGE_SQLITE` - エッジSQLite
- `DOCUMENT_DB` - ドキュメントDB
- `VECTOR_DB` - ベクトルDB
### Worker
- `DURABLE_WORKFLOW` - 耐久ワークフロー
- `EXTERNAL_COMPUTE` - 外部コンピュート
- `SELF_HOSTED_QUEUE` - セルフホストキュー
- `SIMPLE_WEBHOOK` - シンプルWebhook
### Auth
- `DX_FIRST_AUTH` - DX重視
- `DB_INTEGRATED_AUTH` - DB統合
- `ENTERPRISE_AUTH` - エンタープライズ
- `SELF_HOSTED_AUTH` - セルフホスト
### Payment
- `PAYMENT_PROCESSOR` - 決済処理
- `MERCHANT_OF_RECORD` - 販売代行
---
## アンチパターンチェック
### 記入例
```yaml
antipattern_checks:
- id: AP-C1
name: "Serverless + 常駐Worker"
status: NOT_APPLICABLE
note: "Container PaaS選択により該当なし"
- id: AP-D1
name: "Serverless + 標準DB接続"
status: PASSED
note: "Neonコネクションプーラー使用"
```
### ステータス
| Status | 意味 |
| -------------- | ------------------ |
| PASSED | 問題なし |
| FAILED | 問題あり（要対応） |
| MITIGATED | 対策済み |
| NOT_APPLICABLE | 該当なし |
---
## Exit Strategy
```yaml
exit_strategy:
next_tier: T3_GROWTH
migration_triggers:
- condition: "MAU > 50,000"
action: "Container PaaS検討"
- condition: "月額 > $500"
action: "セルフホスト検討"
lock_in_assessment:
- component: vercel
risk: medium
mitigation: "OpenNext移行パス確保"
```
---
## Claude Code Instructions
AIが実装時に参照する指示：
```yaml
claude_instructions:
implementation_notes:
- "Neon接続は必ずpooler URL使用"
- "ファイルアップロードはPresigned URL経由"
prohibited:
- "BullMQの直接実装"
- "60秒超の同期処理"
recommended_patterns:
- "Server Actions活用"
- "Suspenseによる段階的表示"
```
---
## ワークフロー例
### 新規プロジェクト
```
1. アーキタイプ判定（ATLAS Part 1参照）
2. Tier判定（予算・チーム規模）
3. atlas.yaml作成
4. アンチパターンチェック
5. Claude Codeで実装開始
```
### 既存プロジェクト移行
```
1. 現状の技術スタック棚卸し
2. atlas.yamlに記録
3. アンチパターン検知
4. 問題があれば移行計画
5. Exit Strategy更新
```
### レビュー・再評価
```
1. review.next_review_date確認
2. migration_triggers確認
3. 該当すれば移行検討
4. atlas.yaml更新
5. history追記
```
---
## ファイル配置パターン
### パターン1: プロジェクト内完結
```
my-project/
├── .atlas/
│ ├── atlas.yaml # プロジェクト固有
│ ├── atlas-rules.yaml # ルール（コピー）
│ └── atlas-catalog.yaml # カタログ（コピー）
└── src/
```
### パターン2: グローバル共有
```
~/.atlas/
├── atlas-rules.yaml # 共有ルール
└── atlas-catalog.yaml # 共有カタログ
my-project/
├── .atlas/
│ └── atlas.yaml # プロジェクト固有のみ
└── src/
```
### パターン3: モノレポ
```
monorepo/
├── .atlas/
│ ├── atlas-rules.yaml # 共有
│ └── atlas-catalog.yaml
├── apps/
│ ├── web/
│ │ └── atlas.yaml # アプリ固有
│ └── api/
│ └── atlas.yaml
└── packages/
```
---
## バリデーション（将来構想）
```bash
# CLIでの検証（未実装）
atlas validate .atlas/atlas.yaml
# 出力例
✓ Schema valid
✓ Archetype: A3_CONSUMER_APP
✓ Tier: T1_MVP
⚠ Warning: AP-D1 not checked
✗ Error: bullmq incompatible with SERVERLESS_REGIONAL
```
---
## 更新履歴
| Version | Date | Changes |
| ------- | ------- | ------- |
| 1.0 | 2025-01 | 初版 |