philosophy-compliance-workflow

哲学準拠ワークフロースキル

目的

amplihack の中核原則である、徹底したシンプルさ、レンガの哲学、禅のようなミニマリズムに、すべてのコードとアーキテクチャが沿っていることを確認する、体系的な哲学準拠レビューです。このスキルでは、実装が不要な複雑さを伴わず、明確な目的を果たしているかを検証します。

このスキルを使用するタイミング

次の用途に使用します：

• 実装前のアーキテクチャレビュー
• 哲学との整合性を確認するコードレビュー
• リファクタリングの検証（実際にシンプルになったか）
• モジュール設計の検証
• マージ前の哲学準拠チェック
• 過剰なエンジニアリングや複雑さの増大の特定

次の用途には使用しません：

• 機能上のバグ修正（哲学上の問題ではないため）
• パフォーマンス最適化のみ
• ドキュメントの更新
• 純粋な構文やスタイルの問題

哲学の中核原則

シンプルなコードの禅

• 各行が、余計な装飾なしに明確な目的を果たす
• 可能な限りシンプルに、ただし必要以上にシンプルにはしない
• シンプルで明確に定義されたコンポーネントから、複雑なシステムを構築する
• 仮定上の将来ではなく、今必要なことに対処する

レンガの哲学

• レンガ ＝ 明確な責任を 1 つだけ持つ、自己完結型のモジュール
• スタッド ＝ 他のものが接続するための公開コントラクト（関数、API、データモデル）
• 再生成可能 ＝ 接続を壊すことなく、仕様から再構築できる
• 分離されている ＝ すべてのコード、テスト、フィクスチャがモジュールのフォルダー内にある

徹底したシンプルさ

• 動作する最もシンプルな解決策から始める
• 正当な理由がある場合にのみ複雑さを加える
• あらゆる抽象化を疑問視する
• 書かなかったコードにバグはない

レビュープロセス

ステップ 1：対象範囲の特定

レビュー対象を特定します：

• 単一のモジュール、複数のモジュール、またはアーキテクチャ全体
• 最近の変更、またはコードベース全体
• 特定の複雑さに関する懸念、または全般的なレビュー

確認する質問：

• 何がきっかけでこのレビューを行いますか？
• 主な懸念事項は何ですか？
• 期待する成果は何ですか？

ステップ 2：初期分析

コード構造を確認します：

• モジュールの構成と境界
• 公開インターフェース（「スタッド」）
• 依存関係と結合度
• 抽象化レイヤー
• 設定の複雑さ

注意すべき危険信号：

• 1 つのモジュールに複数の責任がある
• モジュールの境界が不明確
• 深い継承階層
• 汎用的な「フレームワーク」コード
• 仮定上のニーズに備えた過剰な将来対応

ステップ 3：哲学に関する質問

各コンポーネントについて、次の 5 つの中核的な質問をします：

1. 必要性：「今、本当にこれが必要ですか？」

   • これは今日、実際の問題を解決していますか？
   • それとも「いつか必要になるかもしれない」という将来に備えたものですか？

2. シンプルさ：「この問題を解決する最もシンプルな方法は何ですか？」

   • レイヤーを取り除けますか？
   • もっと直接的な方法はありますか？

3. モジュール性：「これを自己完結型のレンガにできますか？」

   • 明確な責任を 1 つだけ持っていますか？
   • 接続点（スタッド）は明確ですか？

4. 再生成可能性：「AI が仕様からこれを再構築できますか？」

   • コントラクトは十分に明確ですか？
   • 依存関係は明確に定義されていますか？

5. 価値：「複雑さに見合う価値が得られますか？」

   • これをシンプルにした場合、何が壊れますか？
   • トレードオフは正当化できますか？

ステップ 4：違反事項の特定

重大度別に問題を分類します：

重大（修正必須）：

• 1 つのモジュールに複数の責任がある
• 循環依存
• 公開コントラクトが不明確
• 再生成できない設計
• モジュールの置き換えを妨げる強い結合

警告（修正推奨）：

• 時期尚早な最適化
• 過剰な設定オプション
• 不要な抽象化
• 汎用的な「フレームワーク」パターン
• 現在の必要性を伴わない将来対応

提案（検討）：

• シンプルにできる機会
• 依存関係が少ない代替アプローチ
• 抽象化レイヤーを平坦化する方法
• モジュール境界の改善

ステップ 5：レビューレポートの作成

構造化されたレビュー結果を作成します：

# Philosophy Compliance Review: [Component Name]

## Overall Score: [A/B/C/D/F]

## Summary

[One paragraph overview of findings]

## Strengths (What Aligns)

- [Philosophy-aligned patterns identified]
- [Well-implemented brick designs]
- [Clear simplicity examples]

## Concerns (Warnings)

- [Complexity that should be addressed]
- [Borderline philosophy violations]
- [Opportunities for improvement]

## Violations (Critical Issues)

- [Clear departures from philosophy]
- [Must-fix problems]
- [Blocking issues for philosophy compliance]

## Recommendations

### Immediate Actions (Critical)

1. [Specific fix required with rationale]
2. [Another critical fix]

### Structural Improvements (Important)

1. [Module boundary adjustments]
2. [Decoupling suggestions]

### Simplification Opportunities (Good to Have)

1. [Ways to reduce complexity]
2. [Abstraction removal suggestions]

## Regeneration Assessment

**Can AI rebuild these components from specifications?**

- Module A: [Ready/Needs Work] - [Specific reason]
- Module B: [Ready/Needs Work] - [Specific reason]

**What's blocking regeneration:**

- [List specific issues preventing clear AI regeneration]

## Philosophy Alignment Score

- Ruthless Simplicity: [0-10]/10 - [Rationale]
- Brick Philosophy: [0-10]/10 - [Rationale]
- Zen Minimalism: [0-10]/10 - [Rationale]

**Overall: [Score]/10**

ステップ 6：実行可能なガイダンスを提示する

各違反について、次の内容を提示します：

• 問題の明確な説明
• 哲学に反する理由
• 具体的な修正案
• 修正によって期待される改善
• 優先度（Critical／Important／Nice-to-have）

例：

Issue: SessionManager class has 8 different responsibilities
Violation: Breaks single responsibility (brick philosophy)
Fix: Split into:
  - SessionStore (persistence only)
  - SessionValidator (validation only)
  - SessionLifecycle (creation/expiry only)
Impact: Each brick becomes regeneratable and testable independently
Priority: Critical

哲学の採点基準

徹底したシンプルさ（0～10）

• 10：すべてのコンポーネントに明確な目的があり、複雑さが最小限です
• 8～9：概ねシンプルで、複雑さがわずかに増している程度です
• 6～7：不要な抽象化や将来への備えが一部あります
• 4～5：大幅な過剰設計が見られます
• 0～3：必要以上に複雑で、理解が困難です

ブリックの哲学（0～10）

• 10：すべてのモジュールが自己完結しており、単一の責務が明確です
• 8～9：ほとんどのモジュールがブリックのパターンに従い、結合はわずかです
• 6～7：境界が不明確、または複数の責務を持つモジュールがあります
• 4～5：結合が大きく、契約が不明確です
• 0～3：モノリシック、または密結合で、再生成できません

禅のミニマリズム（0～10）

• 10：シンプルさを重視し、現在のニーズにのみ対応します
• 8～9：概ねミニマルですが、追加機能がいくつかあります
• 6～7：仮定上の将来のニーズに、不必要に対応しています
• 4～5：「念のため」のコードや将来への備えがかなりあります
• 0～3：「いつか必要になるかもしれない」シナリオに備えて過剰設計されています

総合評価

• A（9～10）：哲学との整合性が非常に高いです
• B（7～8）：良好ですが、軽微な改善が必要です
• C（5～6）：許容範囲ですが、注意が必要です
• D（3～4）：整合性が低く、大幅なリファクタリングが必要です
• F（0～2）：全体にわたって、哲学に重大な違反があります

良いパターン（優れた設計の例）

哲学に沿った設計：

• 目的が明確な、単一責務のモジュール
• コードとテストがすべて揃った自己完結型のディレクトリ
• 接続用の明確な公開インターフェース（スタッド）
• 直接的でわかりやすい実装
• 依存関係を最小限に抑える（標準ライブラリを優先）

例：優れたブリックモジュール

authentication/
├── __init__.py        # Exports: authenticate, validate_token
├── core.py           # Implementation (one responsibility)
├── models.py         # User, Token (clear data models)
├── tests/
│   └── test_core.py  # Comprehensive tests
└── README.md         # Regeneration specification

Public Contract (Studs):
- authenticate(username, password) -> Token
- validate_token(token) -> User

One Responsibility: Authentication only (not authorization, not user management)
Regeneratable: Yes, from README.md specification

避けるべきパターン（例）

哲学に反する設計：

• 複数の責務を持つ神オブジェクト
• 明確な根拠のない抽象基底クラス
• シンプルな機能のための複雑な設定システム
• 汎用的で「柔軟な」フレームワーク
• 時期尚早なパフォーマンス最適化

例：悪い設計

user_system/
├── framework.py          # Generic abstraction layer
├── manager.py            # UserManager does everything
├── config/               # Extensive config system
├── plugins/              # Plugin architecture (unused)
└── adapters/             # Future-proofing for other DBs

Problems:
- UserManager handles auth, profile, settings, notifications
- Framework adds complexity without current value
- Plugin system built for "maybe someday"
- Multiple responsibilities, not regeneratable

他のワークフローとの統合

哲学のレビューを組み合わせるタイミング：

• Builder の後：実装されたコードが哲学に従っていることを検証します
• Architect の前：設計仕様がシンプルさを重視していることを確認します
• Reviewer の実施中：哲学をレビュー基準に含めます
• Cleanup と併用：シンプル化・削除すべきものを特定します

デフォルトのワークフロー上の位置：

• アーキテクチャフェーズ：実装開始前
• コードレビューフェーズ：実装後、マージ前
• リファクタリングフェーズ：シンプル化の取り組みを検証

主なモットー

• 「後から複雑さを加えるほうが、取り除くより簡単です」
• 「書かなかったコードにバグはありません」
• 「気の利いた工夫より、明快さを優先します」
• 「最良のコードは、多くの場合、最もシンプルなコードです」
• 「モジュールはブリックであるべきです。自己完結し、再生成できるものです」
• 「これは今必要ですか、それとも将来に備えているだけですか？」
• 「うまくいく可能性のある、最もシンプルな方法は何ですか？」

よくある落とし穴

複雑さの偽装：

• 「これで柔軟になります」→ 過剰設計を意味することがよくあります
• 「後で必要になるかもしれません」→ 現在の必要性がないのに将来に備えています
• 「こちらのほうが汎用的です」→ 汎用化は複雑さにつながることがよくあります
• 「業界のベストプラクティスです」→ 自分たちの規模には適さない場合があります

哲学上の落とし穴：

• 「念のため」に抽象化レイヤーを追加する
• 単一のユースケースのためにフレームワークを構築する
• プラグインが必要になる前にプラグインシステムを作る
• パフォーマンスを計測する前に最適化する
• 仮定上の規模に合わせて設計する

成功基準

哲学レビューが成功したといえるのは、次の条件を満たす場合です。

• 重大な哲学上の違反をすべて特定している
• 実行可能な修正案を提示している
• 違反が重要である理由を説明している
• コンポーネントを客観的に評価している
• 再生成の準備状況を検証している
• 哲学に沿ったパターンを称賛している
• チームをよりシンプルな設計へ導いている

出力成果物

生成されるドキュメント：

• 哲学レビューのレポート（Markdown）
• 優先度付きのアクション項目
• 修正を適用した場合の修正前後の比較
• モジュールごとの再生成評価

保存先：

• ~/.amplihack/.claude/runtime/logs/<session>/philosophy_review_<timestamp>.md
• 修正を適用した場合は、コミットメッセージにリンクを記載します
• amplihack.memory.discoveries の store_discovery() を使用して、学んだパターンをメモリに保存します

覚えておいてください

あなたはシステムの哲学的良心です。複雑さに異議を唱え、シンプルさを称え、あらゆるアーキテクチャ上の判断が、優美で本質的なソフトウェアという禅の理想に近づくようにしてください。

目標は完璧ではありません。よりシンプルで明快、かつ再生成しやすいコードを目指して、継続的に改善することです。