Skip to content

Commit 7745bba

Browse files
web-flowclaude
web-flow
and
claude
committed
docs: Config層独立性の理由を文書化
将来の開発者が誤ってdomain importを追加しないよう、 Config層の独立性要件とその理由を明確に文書化。 ## 追加箇所 1. ARCHITECTURE.md - 依存関係ルールにConfig層の特別ルールを追加 - ⚠️ CRITICAL セクションで禁止事項と理由を明記 2. config/__init__.py - docstring冒頭に独立性の警告を追加 - 型・例外・定数の独自定義ファイルを明記 3. config/exceptions.py - なぜdomain.exceptions.ConfigErrorを使わないのかを説明 - エラーキャッチ方法のWarningを追加 ## 理由 Config層は digest-config スキルの本体であり、 Claudeプラグインとして単独でロード可能である必要がある。 Domain層への依存はCircular Importの原因となる。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent e7068a7 commit 7745bba

8 files changed

Lines changed: 225 additions & 4 deletions

File tree

‎EpisodicRAG/docs/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,15 @@ AI/Claudeエージェント向けの技術仕様ハブです。
6666

6767
---
6868

69+
## Learning Resources
70+
71+
| 目的 | ドキュメント |
72+
|------|-------------|
73+
| 学習パス | [LEARNING_PATH.md](dev/LEARNING_PATH.md) |
74+
| 設計判断 | [DESIGN_DECISIONS.md](dev/DESIGN_DECISIONS.md) |
75+
76+
---
77+
6978
## Developer Documentation
7079

7180
| 目的 | ドキュメント | 概要 |

‎EpisodicRAG/docs/dev/ARCHITECTURE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,8 +151,20 @@ infrastructure/ ← domain/ のみ
151151
application/ ← domain/ + infrastructure/
152152
↑
153153
interfaces/ ← application/
154+
155+
config/ ← 何にも依存しない（完全独立）
154156
```
155157

158+
> ⚠️ **CRITICAL: Config層の独立性**
159+
>
160+
> `config/` パッケージは **domain/ を含む他のすべての層から完全に独立** していなければなりません。
161+
>
162+
> **理由**: Config層は `digest-config` スキルの本体であり、Claudeプラグインとして単独でロード可能である必要があります。Domain層への依存があると、プラグインの初期化順序やCircular Importの問題が発生します。
163+
>
164+
> **禁止**: `from domain import ...` を config/ 内で使用しないでください。
165+
>
166+
> Config層が必要とする型・例外・定数は、すべて `config/types.py`, `config/exceptions.py`, `config/constants.py` に独自定義されています。
167+
156168
```mermaid
157169
graph BT
158170
subgraph "Interfaces層"

‎EpisodicRAG/docs/dev/DESIGN_DECISIONS.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,38 @@
144144

145145
---
146146

147+
## 教材としての設計意図
148+
149+
このプロジェクトは実用的なプラグインであると同時に、エンタープライズPython開発のベストプラクティスを学ぶ教材としても設計されています。
150+
151+
### なぜClean Architectureを採用したか
152+
153+
| 観点 | 実用的理由 | 教育的理由 |
154+
|------|-----------|-----------|
155+
| テスタビリティ | 層ごとに独立してテスト可能 | 依存関係ルールの実践例として最適 |
156+
| 依存方向の制御 | 変更の影響範囲を限定 | 「どの層に何を置くか」の判断基準を学べる |
157+
| 将来の拡張性 | 新機能追加が容易 | 大規模プロジェクトでの設計手法を小規模で体験 |
158+
159+
### なぜSSoTを徹底したか
160+
161+
| 観点 | 実用的理由 | 教育的理由 |
162+
|------|-----------|-----------|
163+
| メンテナンス性 | 変更箇所が1箇所で済む | 「情報の重複を避ける」原則の実践 |
164+
| 一貫性 | 不整合の防止 | リファクタリング耐性の高い設計を学べる |
165+
166+
### なぜ複数のデザインパターンを使用したか
167+
168+
| 観点 | 実用的理由 | 教育的理由 |
169+
|------|-----------|-----------|
170+
| 問題解決 | 各パターンが解決する問題に対する最適解 | 実際のプロジェクトでパターンがどう使われるか学べる |
171+
| コード品質 | 保守性・拡張性の向上 | 「パターンのための実装」ではなく「問題解決のための選択」を体験 |
172+
173+
### 学習リソース
174+
175+
このプロジェクトでの学習パスについては [LEARNING_PATH.md](LEARNING_PATH.md) を参照してください。
176+
177+
---
178+
147179
## 参考リンク
148180

149181
- [Clean Architecture (Robert C. Martin)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

‎EpisodicRAG/docs/dev/LEARNING_PATH.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
[EpisodicRAG](../../README.md) > [Docs](../README.md) > LEARNING_PATH
2+
3+
# Learning Path - EpisodicRAGで学ぶエンタープライズPython開発
4+
5+
このドキュメントでは、EpisodicRAGプラグインのコードベースを通じて学べるエンタープライズPython開発のベストプラクティスを紹介します。
6+
7+
---
8+
9+
## このプロジェクトで学べること
10+
11+
### 1. Clean Architecture（4層構造）
12+
13+
EpisodicRAGは依存関係ルールに基づく4層構造を採用しています。
14+
15+
| レイヤー | ディレクトリ | 責務 |
16+
|----------|-------------|------|
17+
| Domain | `scripts/domain/` | ビジネスロジックの純粋な定義（外部依存なし） |
18+
| Infrastructure | `scripts/infrastructure/` | 外部I/Oの抽象化（JSON、ファイル、ログ） |
19+
| Application | `scripts/application/` | ユースケースの実装 |
20+
| Interfaces | `scripts/interfaces/` | エントリーポイント |
21+
22+
**学習ポイント**:
23+
- `scripts/domain/` を読む → 外部依存のない純粋な定義を理解
24+
- `scripts/application/` を読む → 依存関係ルールの実践を確認
25+
- 参照: [ARCHITECTURE.md](ARCHITECTURE.md#clean-architecture)
26+
27+
### 2. Single Source of Truth (SSoT)
28+
29+
情報の重複を避け、一元管理する原則を徹底しています。
30+
31+
| 対象 | SSoT | 実装 |
32+
|------|------|------|
33+
| 用語定義 | `README.md` | 用語集として機能 |
34+
| バージョン | `plugin.json` | 他ファイルはここを参照 |
35+
| 設定仕様 | `docs/dev/api/config.md` | 詳細は1箇所のみ |
36+
37+
**学習ポイント**:
38+
- `README.md` → 用語集としての機能を確認
39+
- `plugin.json` → バージョンSSoTの実装を確認
40+
- `docs/dev/API_REFERENCE.md` → リンク集としてSSoT違反を回避する設計
41+
- 参照: [CONTRIBUTING.md](../../CONTRIBUTING.md#single-source-of-truth-ssot-原則)
42+
43+
### 3. デザインパターン実践
44+
45+
実際の問題解決に適用されたデザインパターンを学べます。
46+
47+
| パターン | 実装箇所 | 学習ポイント |
48+
|---------|---------|-------------|
49+
| Facade | `DigestConfig`, `ShadowUpdater` | 複雑なサブシステムの隠蔽 |
50+
| Repository | `ShadowIO`, `GrandDigestManager` | データアクセスの抽象化 |
51+
| Singleton | `LevelRegistry` | 設定の一元管理 |
52+
| Strategy | `LevelBehavior` | 振る舞いの交換可能性 |
53+
| Builder | `RegularDigestBuilder` | 複雑なオブジェクト構築 |
54+
| Factory | `get_level_registry()` | オブジェクト生成の抽象化 |
55+
56+
**学習ポイント**:
57+
- 各パターンの実装ファイルを読む
58+
- 参照: [API_REFERENCE.md](API_REFERENCE.md#デザインパターン)
59+
- 参照: [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md)
60+
61+
### 4. テスト設計
62+
63+
層別テストと高いカバレッジを実現するテスト設計を学べます。
64+
65+
| 観点 | 実装 |
66+
|------|------|
67+
| 層別テスト | `scripts/test/` 配下でレイヤーごとにテストを分離 |
68+
| フィクスチャ | `conftest.py` で共通フィクスチャを定義 |
69+
| マーカー | `@pytest.mark.slow` 等でテスト実行戦略を制御 |
70+
71+
**学習ポイント**:
72+
- `scripts/test/` のファイル命名規則を確認
73+
- 参照: [CONTRIBUTING.md](../../CONTRIBUTING.md#テスト)
74+
75+
### 5. ドキュメント設計
76+
77+
オーディエンス別に整理されたドキュメント構造を学べます。
78+
79+
| 観点 | 実装 |
80+
|------|------|
81+
| オーディエンス分離 | `docs/user/` vs `docs/dev/` |
82+
| パンくずナビ | 各ファイル先頭に配置 |
83+
| SSoT準拠 | 相互リンクで詳細を1箇所に集約 |
84+
85+
**学習ポイント**:
86+
- `docs/` のディレクトリ構造を確認
87+
- 各ファイルの先頭パンくずを確認
88+
89+
---
90+
91+
## 推奨学習順序
92+
93+
```
94+
1. README.md → プロジェクト概要と用語を把握
95+
↓
96+
2. ARCHITECTURE.md → 技術構造を理解
97+
↓
98+
3. domain/ → 純粋なビジネスロジックを読む
99+
↓
100+
4. application/ → ユースケース実装を読む
101+
↓
102+
5. DESIGN_DECISIONS.md → 設計判断の理由を理解
103+
↓
104+
6. test/ → テスト設計を学ぶ
105+
```
106+
107+
---
108+
109+
## 関連ドキュメント
110+
111+
- [ARCHITECTURE.md](ARCHITECTURE.md) - 技術仕様
112+
- [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) - 設計判断
113+
- [API_REFERENCE.md](API_REFERENCE.md) - API仕様
114+
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 開発ガイド

‎EpisodicRAG/scripts/application/shadow/shadow_updater.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,13 @@ class ShadowUpdater:
2828
（FileAppender, CascadeProcessor, PlaceholderManager）を統合して
2929
シンプルなAPIを提供します。
3030
31+
Design Pattern: Facade
32+
複雑なサブシステムをシンプルなインターフェースで隠蔽。
33+
34+
Learning Point:
35+
呼び出し側は内部コンポーネントの存在を意識せずにShadow操作が可能。
36+
内部実装の変更が外部APIに影響しないため、保守性が向上。
37+
3138
設計意図:
3239
- 呼び出し側は内部コンポーネントの存在を意識せずにShadow操作が可能
3340
- 内部コンポーネントの変更が外部に影響しない（カプセル化）

‎EpisodicRAG/scripts/config/__init__.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,21 @@
55
66
Plugin自己完結版：Plugin内の.claude-plugin/config.jsonから設定を読み込む
77
8+
## ⚠️ CRITICAL: Config層の独立性
9+
10+
このパッケージは **domain/ を含む他のすべての層から完全に独立** しています。
11+
12+
**理由**: Config層は `digest-config` スキルの本体であり、Claudeプラグインとして
13+
単独でロード可能である必要があります。Domain層への依存があると、プラグインの
14+
初期化順序やCircular Importの問題が発生します。
15+
16+
**禁止**: `from domain import ...` をこのパッケージ内で使用しないでください。
17+
18+
Config層が必要とする型・例外・定数は、すべて以下に独自定義されています:
19+
- `config/types.py` - TypedDict定義
20+
- `config/exceptions.py` - ConfigError例外
21+
- `config/constants.py` - LEVEL_CONFIG, LEVEL_NAMES
22+
823
## 設計意図
924
1025
ARCHITECTURE: Thin Facade Pattern
@@ -69,6 +84,14 @@ class DigestConfig:
6984
薄い Facade として機能し、各コンポーネントに責任を委譲。
7085
後方互換性を維持しつつ、内部実装を分離。
7186
87+
Design Pattern: Facade
88+
複雑なサブシステム（PathResolver, ThresholdProvider等）を
89+
単純なインターフェースで隠蔽。
90+
91+
Learning Point:
92+
利用者は DigestConfig のみをインポートすれば設定にアクセス可能。
93+
内部コンポーネントへの直接アクセスを防ぎ、変更に強い設計を実現。
94+
7295
Components:
7396
- _config_loader: ConfigLoader - 設定ファイルの読み込み
7497
- _path_resolver: PathResolver - パス解決

‎EpisodicRAG/scripts/config/exceptions.py‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,18 @@
66
Config層をDomain層から独立させるための例外クラス。
77
シンプルな例外として実装し、DiagnosticContextは持たない。
88
9+
## ⚠️ なぜ domain.exceptions.ConfigError を使わないのか
10+
11+
Config層は `digest-config` スキルの本体であり、Claudeプラグインとして
12+
**単独でロード可能**である必要があります。
13+
14+
Domain層への依存があると:
15+
1. プラグイン初期化時にDomain層全体がロードされる
16+
2. Circular Import の問題が発生する可能性がある
17+
3. Config層の変更がDomain層に影響する
18+
19+
このため、Config層は独自の例外クラスを持ちます。
20+
921
Usage:
1022
from config.exceptions import ConfigError
1123
@@ -17,18 +29,23 @@ class ConfigError(Exception):
1729
"""
1830
設定関連エラー
1931
20-
Config層専用の例外クラス。Domain層のConfigErrorとは独立。
32+
Config層専用の例外クラス。Domain層の例外とは**完全に独立**。
2133
2234
Examples:
2335
- config.json が見つからない
2436
- config.json のフォーマットが不正
2537
- 必須の設定キーが存在しない
2638
- 無効なレベルが指定された
2739
28-
Note:
40+
Warning:
2941
Domain層のEpisodicRAGErrorを継承しないため、
30-
`except EpisodicRAGError` ではキャッチされない。
31-
これはConfig層の独立性を保つための意図的な設計。
42+
`except EpisodicRAGError` ではキャッチされません。
43+
これはConfig層の独立性を保つための**意図的な設計**です。
44+
45+
Config層のエラーをキャッチする場合は:
46+
from config.exceptions import ConfigError
47+
except ConfigError:
48+
...
3249
"""
3350

3451
def __init__(self, message: str) -> None:

‎EpisodicRAG/scripts/domain/level_registry.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,13 @@ class LevelBehavior(ABC):
112112
新しい振る舞いが必要な場合、このクラスを継承して実装を追加。
113113
既存コードを修正せずに拡張可能（OCP準拠）。
114114
115+
Design Pattern: Strategy
116+
振る舞いをカプセル化し、実行時に交換可能にする。
117+
118+
Learning Point:
119+
新しいレベルタイプを追加する際は、このクラスを継承した
120+
新クラスを作成するだけで対応可能。既存コードの修正は不要（OCP）。
121+
115122
## ARCHITECTURE: Strategy Pattern の Context
116123
このクラスが Strategy の抽象インターフェースを定義。
117124
StandardLevelBehavior, LoopLevelBehavior が具象 Strategy。

0 commit comments

Comments
 (0)