# B00 情報システム開発ガイド

**最終更新**: 2025年8月30日（src/noveler構造対応・パス更新）

## 🎯 目的

CLI スクリプト開発に必要な **最小限かつ本質的な知識** を 1 冊に集約し、迷わず実装と改善サイクルを回せるようにする。

> **原則**
> 1. DRY ― 重複排除
> 2. KISS ― シンプルさ優先
> 3. YAGNI ― 今すぐ必要ないものは足さない

---

## 1. システムアーキテクチャ基盤（B10 系統）

### レイヤードアーキテクチャ

| 層                  | 役割                | 主なモジュール                              | 設計原則 |
| ------------------ | ----------------- | ------------------------------------ | ------ |
| **Presentation**   | CLI / API エンドポイント | `src/noveler/presentation/cli/`       | UI/UX、入力検証 |
| **Application**    | ユースケース調整          | `src/noveler/application/use_cases/`  | ビジネス調整 |
| **Domain**         | ビジネスロジック          | `src/noveler/domain/{entities,services}` | 核心ロジック |
| **Infrastructure** | DB / FS / 外部 API  | `src/noveler/infrastructure/`         | 技術実装 |

### 設計品質特性

**機能適合性**: 要求機能の完全実装・正確性
**保守性**: モジュール独立性・再利用性・変更容易性
**信頼性**: 障害耐性・可用性・回復性

* 依存方向は **外 -> 内** の一方向。
* アーキテクチャ決定は ADR で 1 件 1 ファイル (`docs/adr/NNN-title.md`).

---

## 2. 統合開発プロセス（B20 系統）

### アジャイル TDD サイクル

1. **仕様書作成 (SPEC-XXX)**
   * 必須テンプレート: `specs/{ID}.md`
   * ユーザーストーリー形式: "As a [役割] I want [機能] So that [価値]"

2. **RED**: 失敗するテストを追加（`tests/unit`）
3. **GREEN**: 最小実装でテストを通す
4. **REFACTOR**: 重複排除・命名整理
5. **PR**: GitHub Actions で CI パス → レビュー

### 開発手法選択指針

| プロジェクト特性 | 推奨手法 | 適用理由 |
|----------------|---------|---------|
| 要求明確・安定 | ウォーターフォール | 計画性重視 |
| 要求不明確・変化 | アジャイル・スクラム | 変化対応 |
| CLI ツール開発 | TDD + 継続的統合 | 品質と速度 |

> **ブランチ命名規則**
> `feature|fix|refactor: SPEC-<ID>-<slug>`

---

## 3. 品質管理・テスト戦略（B30 系統）

### テストピラミッド

```
   ▲  5% E2E          (tests/e2e)
   │ 20% Integration  (tests/integration)
   ▼ 75% Unit         (tests/unit)
```

### 品質特性の実装

**性能効率性**: 応答時間2秒以内、1000リクエスト/秒
**使用性**: 習得容易性、操作明確性
**セキュリティ**: 機密性・完全性・可用性（CIA）

### テスト実践原則

* **FIRST 原則**: Fast, Independent, Repeatable, Self‑Validating, Timely
* すべてのテストに `@pytest.mark.spec("SPEC-XXX")` を付与
* **非機能要件テスト**: パフォーマンス、セキュリティ、可用性の検証

---

## 4. 品質ゲート & 共通コンポーネント（B32）

| ゲート        | ツール                            | Fail 条件     |
| ---------- | ------------------------------ | ----------- |
| Lint       | `ruff`                         | Error > 0   |
| Type‑check | `mypy`                         | Error > 0   |
| Duplicate  | `detect_duplicate_patterns.py` | 1 つでも検出     |
| Test       | `pytest --cov`                 | カバレッジ < 85% |

* 共通コンソール・エラーハンドラを**必ず**使用。新規実装は禁止。

---

## 5. セキュリティ基礎（B40 系統）

* **CIA**: 機密性・完全性・可用性
* **OWASP Top 3** のみ必須

  1. アクセス制御不備 → RBAC + 所有者チェック
  2. 暗号化不備 → `bcrypt`, `cryptography.fernet`
  3. インジェクション → パラメータ化クエリ / `subprocess.run([...], check=True)`

---

## 6. 運用 & モニタリング（B50 系統）

* 品質チェック（MCP）: `noveler mcp call run_quality_checks '{"episode_number": 1, "additional_params": {"format": "summary"}}'`
* 原稿整形（MCP）: `noveler mcp call polish_manuscript '{"episode_number": 1, "file_path": "40_原稿/第001話_サンプル.md", "stages": ["stage2"], "dry_run": true}'`
* アーティファクト（MCP）: `noveler mcp call list_artifacts '{"episode_number": 1}'` / `noveler mcp call restore_manuscript_from_artifact '{"episode_number": 1, "artifact_id": "..."}'`
* 監視: GitHub Actions + ChatOps 通知（失敗時に Slack Webhook）

---

## 7. CI/CD・GitHub Actions（B70 系統）

### 継続的統合・デプロイメント

**CI基本原則**:
- **頻繁統合**: 小さな変更を日に数回統合
- **自動化**: ビルド・テスト・デプロイの完全自動化
- **高速フィードバック**: 問題の早期発見・通知

**デプロイメントパイプライン**:
```
Code Commit → Build & Test → Staging Deploy → Production Deploy
```

### GitHub Actions実装例

```yaml
name: CI/CD Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with: {python-version: "3.12"}
      - run: pip install .[dev]
      - run: ruff check src/
      - run: mypy src/
      - run: pytest --cov=scripts --cov-report=xml

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: quality
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy to production"
```

**品質ゲート設定**:
- **Lint**: Error > 0でFail
- **Type Check**: mypy Error > 0でFail
- **Test Coverage**: 85%未満でFail
- **Security Scan**: Critical脆弱性でFail

---

## 8. プロジェクト管理基礎（B20統合済み）

### スコープ・スケジュール・コスト管理

**スコープ管理**:
- WBS（作業分解構造）でタスク階層化
- スコープクリープ対策と変更管理

**スケジュール管理**:
- クリティカルパス法による工期最適化
- 依存関係とリソース制約の管理

**コスト管理**:
- 工数見積り（人件費・設備費・間接費）
- 価値分析（EVA）による進捗測定

### アジャイル実践管理

```yaml
スプリント運営:
  計画: 目標設定とタスク分解
  実行: デイリースタンドアップと進捗管理
  レビュー: 成果デモと顧客フィードバック
  改善: レトロスペクティブとプロセス最適化
```

---

## 9. リスク管理・成功要因（B24 系統）

### リスク管理プロセス

**リスク特定・分析**:
```
影響度 × 発生確率 = リスク値
技術リスク: 新技術採用、パフォーマンス未達
管理リスク: スケジュール遅延、予算超過
外部リスク: 要件変更、法規制変更
```

**対応戦略**:
- **回避**: リスク発生を防ぐ（技術選定変更）
- **軽減**: 影響を減らす（プロトタイプ開発）
- **転嫁**: 他者に移す（外部委託・保険）
- **受容**: リスクを受け入れる（予備費確保）

### 開発成功要因

**技術的要因**: 適切アーキテクチャ・品質作り込み・自動化推進
**管理的要因**: 明確ビジョン・効果的コミュニケーション・早期リスク対応
**組織的要因**: スキル開発・プロセス標準化・ツール整備

---

## 10. よく使うコマンド & スニペット

| タスク             | コマンド                                          |
| --------------- | --------------------------------------------- |
| 新プロジェクト作成       | 参照: `docs/guides/quick_start.md`                 |
| ユニットテスト高速実行     | `pytest -q -m unit`                           |
| 直近失敗の再実行         | `make test-last`                                |
| 差分テスト（git）        | `make test-changed`                             |
| テスト出力の最適化（LLM） | `bin/test-json -q`                              |
| ドメインオブジェクト生成    | `python -m scripts.tools.make_entity Episode` |
| YAML から JSON 変換 | `python -m scripts.tools.yaml2json file.yaml` |

---

## 11. テンプレートリンク集

* `templates/adr.md` ― アーキテクチャ決定記録
* `templates/spec.md` ― 仕様書
* `templates/test_case.md` ― テストケース雛形

---

## Appendix: ファイル構成

```
├── src/noveler/
│   ├── domain/
│   ├── application/
│   ├── infrastructure/
│   └── presentation/
├── tests/
├── specs/
└── docs/adr/
```

---

### 更新履歴

| Version | Date       | Summary                |
| ------- | ---------- | ---------------------- |
| 1.0     | 2025‑08‑08 | 初版（従来 B00‑B71 を統合・簡素化） |
| 2.0     | 2025‑08‑08 | B01統合版（理論基盤+プロジェクト管理強化） |


### Domain独立性（実装要点）
- Domain→Presentation/Infrastructure の静的importは禁止（importlinterで検査）。
- console出力はdomain_console経由、loggingはILogger/NullLogger系、パスや設定等は manager/proxy を介す。
- 互換レイヤが必要な場合（テストのpatch対象など）は安全ラッパーを提供する（例: get_logger, create_path_service）。
