Aifp

## 🚀 AIFP: AI機能的手続き型プログラミング

[![PyPI](https://img.shields.io/pypi/v/aifp)](https://pypi.org/project/aifp/)

> **AIによって生成され、AIによって管理されるコードベース向けに設計された言語非依存のプログラミングパラダイム**

---

## 🚀 クイックスタート
AIFP（AI Functional Procedural）は、純粋な関数型プログラミングの原則、手続き型の実行パターン、データベース駆動のプロジェクト管理、およびディレクティブベースのAIガイダンスを組み合わせたプログラミングパラダイムです。これにより、AIと人間のコラボレーションが最適化され、コードベースの開発と管理が効率的に行えます。

### 前提条件
- **Python 3.11+** （全体で使用される型ヒント構文に必要）

### インストール
#### 方法1: pip install（推奨）
```bash
pip install aifp

これにより、MCPサーバーがインストールされ、aifpコマンドが使用可能になります。AIFPは、外部依存関係は1つだけ（ファイルシステム監視用のwatchdog）で、JSON-RPCサーバー自体は純粋なPython標準ライブラリで構成されています。

方法2: 手動インストール（GitHubからダウンロード）

1. リポジトリをダウンロード （zipダウンロードまたはgit clone）
2. src/aifp/フォルダを見つける — これが完全なMCPサーバーパッケージです
3. aifp/フォルダをMCPサーバーを保管する場所にコピーする

# 例: MCPサーバーディレクトリにコピー
cp -r src/aifp/ ~/mcp-servers/aifp/

唯一のランタイム依存関係（watchdog）は自動的にインストールされます。aifp/フォルダには、サーバーが必要とする他のすべてのものが含まれています：ヘルパー関数、ディレクティブ、データベーススキーマ、および事前にパブリッシュされたaifp_core.db。

AIクライアントにシステムプロンプトを追加する

この手順は必須です。 システムプロンプトは、AIにAIFPツールを積極的に使用するよう指示するものです。これがないと、MCPサーバーは呼び出されることのない受動的なツールの集まりに過ぎません。

システムプロンプトをターミナルに出力し、AIクライアントにコピーして貼り付けます：

python3 -m aifp --system-prompt

システムプロンプトはパッケージに含まれているため、別のファイルやダウンロードは必要ありません。これはすべてのインストール方法（pip、venv、手動）で機能します。

貼り付ける場所 （AIクライアントによって異なります）：

AIクライアントを設定する

AIクライアントの設定でAIFP MCPサーバーを登録します。サーバーは標準入出力トランスポートを使用します — JSON-RPCメッセージを標準入力から読み取り、応答を標準出力に書き込みます。

Claude Desktop

claude_desktop_config.jsonを編集します：

{
  "mcpServers": {
    "aifp": {
      "command": "python3",
      "args": ["-m", "aifp"],
      "env": {}
    }
  }
}

方法2（手動インストール） を使用した場合は、aifp/フォルダの親ディレクトリをPYTHONPATHに追加して、Pythonがそれを見つけられるようにします：

{
  "mcpServers": {
    "aifp": {
      "command": "python3",
      "args": ["-m", "aifp"],
      "env": {
        "PYTHONPATH": "/path/to/parent-of-aifp-folder"
      }
    }
  }
}

たとえば、aifp/を~/mcp-servers/aifp/にコピーした場合は、PYTHONPATHを~/mcp-serversに設定します。

仮想環境にインストールした場合 は、venvのPythonの完全パスを使用して、Claude Desktopが正しいインタープリターを使用するようにします：

{
  "mcpServers": {
    "aifp": {
      "command": "/path/to/venv/bin/python3",
      "args": ["-m", "aifp"],
      "env": {}
    }
  }
}

Claude Code

claude mcp addを使用してサーバーを登録します。このコマンドは、AIFPで管理したいプロジェクトフォルダ内から実行してください。

まずスコープを選択してください。 AIFPは厳格な関数型プログラミングを強制し、OOPコードベースを積極的に拒否します。OOPを使用する他のプロジェクトやAIFPが必要ないプロジェクトで作業する場合は、--scope userを避けてください — これは、開くすべてのプロジェクトでサーバーを有効にします。

pip install（システム全体）：

claude mcp add --transport stdio --scope project aifp -- python3 -m aifp

pip install（仮想環境） — venvのPythonパスを使用します：

claude mcp add --transport stdio --scope project aifp -- /path/to/venv/bin/python3 -m aifp

単純なpython3はシステムのPythonを解決し、パッケージがインストールされていない場合があります。venvのインタープリターの完全パスを使用して、MCPサーバーのサブプロセスがインストールされたパッケージを見つけられるようにします。

手動インストールまたはソースから実行 — PYTHONPATHをaifp/フォルダの親ディレクトリに設定します：

claude mcp add --transport stdio --scope project --env PYTHONPATH=/path/to/parent-of-aifp aifp -- python3 -m aifp

クイックリファレンス：

注意: すべてのフラグ（--transport, --scope, --env）はサーバー名の前に指定する必要があります。--は名前とコマンドを区切ります。Claude Code内で/mcpを使用してサーバーが接続されていることを確認してください。

Claude Code: すべてのAIFPツールを事前承認する（オプション）

Claude Codeは、新しいMCPツールが初めて呼び出されるたびに承認を求めます。207個のツールがある場合、207回の承認プロンプトが表示されます。これをスキップするには、事前に作成されたパーミッションファイルをプロジェクトの.claude/フォルダにコピーします：

# プロジェクトルートに.claude/フォルダが存在しない場合は作成する
mkdir -p /path/to/your/project/.claude

# パーミッションファイルをコピーする
cp documentation/settings.local.json /path/to/your/project/.claude/

これにより、プロジェクトの.claude/フォルダにsettings.local.jsonが配置され、すべてのAIFPツールが事前に許可されます。Claude Codeは自動的にこれを読み取り、承認プロンプトは必要ありません。

注意: このファイルには、enableAllProjectMcpServersとenabledMcpjsonServersの設定も含まれているため、プロジェクトに.mcp.jsonがある場合はAIFPサーバーが自動的に起動します。

その他のMCPクライアント

サーバーは標準入出力トランスポートを使用します。クライアントをpython3 -m aifp（またはvenvのPythonの完全パス）に向けてください。手動インストールの場合は、PYTHONPATHにaifp/フォルダの親ディレクトリが含まれていることを確認してください。APIキーや認証は必要ありません。

動作の仕方

サーバーは、Model Context Protocolを使用して標準入出力を介して通信します。aifp_core.db（ディレクティブデータベース）は、自身のインストールに対して相対的に解決されるため、環境変数は必要ありません。

接続されると、AIはすべてのインタラクションでaifp_run()を呼び出します（システムプロンプトによってガイドされます）。プロジェクトの状態は、作業ディレクトリの.aifp-project/に保存され、プロジェクトを初期化すると自動的に作成されます。

プロジェクトの初期化

AIアシスタントに次のように指示します：

"Initialize AIFP for my project"

AIはaifp_initを呼び出し、プロジェクトルートに.aifp-project/フォルダを作成します。このフォルダには、プロジェクトの状態を追跡するためのデータベース、ユーザー設定、およびProjectBlueprintドキュメントが含まれています。これらのファイルと直接やり取りする必要はありません — MCPサーバーが自動的に管理します。

✨ 主な機能

• 包括的なMCPツール — 4つのSQLiteデータベースに対する完全なCRUD操作を提供し、プロジェクト管理、FPディレクティブ、ユーザー設定、およびカスタム自動化ディレクティブをカバーします。
• 純粋な関数型プログラミングの強制 — AIはデフォルトでFP準拠のコードを記述します（純粋な関数、不変性、OOPなし）。
• データベース駆動の永続的なメモリ — プロジェクトの状態はセッションをまたいで保持され、コンテキストの損失がありません。
• ディレクティブベースのワークフロー — 決定論的なトランク → ブランチ → フォールバックの実行パターンを持ちます。
• 有限の完了パス — プロジェクトには定義された段階、マイルストーン、およびタスクがあり、作業は完了に向かって収束します。
• 2つのユースケース — 通常のソフトウェア開発（ユースケース1）またはカスタムディレクティブ自動化（ユースケース2）。
• ユーザー設定の学習 — AIは、ディレクティブごとのキーバリューオーバーライドを通じてコーディングスタイルに適応します。
• Git統合 — FPベースのブランチ管理とコンフリクト解決を提供します。
• 最小限の依存関係 — 1つのランタイムパッケージ（watchdog）で、カスタムJSON-RPCサーバーは標準ライブラリのみを使用します。
• コスト意識のある設計 — すべてのトラッキング/分析機能はデフォルトで無効になっています。

トークンオーバーヘッド

AIFPのプロジェクト管理は、各セッションにトークンのオーバーヘッドを追加します。データベース操作（ファイルの追跡、タスクの更新、マイルストーンの管理）は、コードの記述自体に加えてトークンを消費します。これを最小限に抑えるために取り組んでいます — 継続呼び出しは軽量で（約2kトークン）、バッチヘルパーによって往復回数が減少し、すべてのオプションのトラッキングはデフォルトでオフになっています。

報酬はプロジェクトの規模に伴って得られます。AIFPを使用しない場合、新しいセッションごとにAIはディレクトリを再スキャンし、ソースファイルを再読み取り、コンテキストを最初から再構築する必要があります — これらのコストはコードベースのサイズとともに増加します。AIFPを使用すると、データベースが即座に構造化されたコンテキストを提供します：AIはどのファイルが存在し、それらにどの関数が含まれているか、作業がどこで中断されたか、次に何が必要かを正確に知っています。少数のファイルを超えるプロジェクトでは、最初のトラッキングコストは再発見作業の削減によって何度も回収されます。

📦 インストール

前提条件

• Python 3.11+ （全体で使用される型ヒント構文に必要）

インストール方法

方法1: pip install（推奨）

pip install aifp

方法2: 手動インストール（GitHubからダウンロード）

1. リポジトリをダウンロード（zipダウンロードまたはgit clone）
2. src/aifp/フォルダを見つける
3. aifp/フォルダをMCPサーバーを保管する場所にコピーする

cp -r src/aifp/ ~/mcp-servers/aifp/

💻 使用例

例1: プロジェクトの初期化

ユーザープロンプト： "Help me build a calculator"

ツール呼び出し：

1. aifp_run(is_new_session=true)
   → 戻り値: セッションバンドル（ディレクティブ名、設定、プロジェクトステータス、サポートコンテキスト）
   → ステータス表示: .aifp-project/ が存在しない — 未初期化

2. aifp_init(project_root="/home/user/calculator")
   → 戻り値: { success: true, message: "Project initialized" }

動作内容：

• AIがプロジェクトが存在しないことを検出し、自動的にaifp_initヘルパーを呼び出す
• .aifp-project/ディレクトリを作成し、project.db、user_preferences.db、およびProjectBlueprint.mdを作成する
• プロジェクトメタデータ（名前、ルートパス、インフラストラクチャ）を登録する
• デフォルトのユーザー設定とバックアップ構成を挿入する
• AIがフェーズ2に入り、ユーザーとプロジェクトの形状について話し合う（インフラストラクチャ、目的、目標）
• project_discoveryにルーティングして共同プランニングを行う（テーマ、フロー、完了パス、マイルストーン）

例2: FP準拠のコードの記述

ユーザープロンプト： "Write a multiply_matrices function"

ツール呼び出し：

1. aifp_run(is_new_session=false)
   → 戻り値: 軽量ガイダンス

2. reserve_file(project_root="/home/user/calculator", name="matrix_operations", ...)
   → 戻り値: { success: true, data: { id: 42 } }

3. reserve_function(project_root="/home/user/calculator", name="multiply_matrices", file_id=42, ...)
   → 戻り値: { success: true, data: { id: 99 } }

   (AIがsrc/matrix_operations_id_42.pyにFP準拠のコードを書き込む)

4. finalize_file(project_root="/home/user/calculator", file_id=42, path="src/matrix_operations_id_42.py", ...)
   → 戻り値: { success: true }

5. finalize_function(project_root="/home/user/calculator", function_id=99, line_start=5, line_end=25, ...)
   → 戻り値: { success: true }

動作内容：

• 書き込み前にproject.dbでファイルと関数を予約する（名前にIDを埋め込む）
• AIがFPベースラインに従って純粋な関数型コードを書き込む（OOPなし、変更なし、明示的なパラメータ）
• ファイルと関数を行番号とメタデータで完了する
• プロジェクトデータベースがコード構造を追跡し、将来のセッションですぐに取得できるようにする

例3: 作業の再開 / ステータスの確認

ユーザープロンプト： "Where are we?" または "Continue working"

ツール呼び出し：

1. aifp_run(is_new_session=false)
   → 戻り値: ガイダンス + 一般的な開始ポイント

   (AIがキャッシュされたコンテキストから応答する — コンテキストが古い場合を除き、追加のDB呼び出しは必要ない
    その場合:)

2. aifp_status(project_root="/home/user/calculator", type="detailed")
   → 戻り値: プロジェクトメタデータ、アクティブなマイルストーン、現在のタスク、最近のノート、警告

動作内容：

• AIが現在のマイルストーン、アクティブなタスク、および次のステップを提示する
• project_continue_on_start=trueの場合、AIが自動的に次のタスクを引き継ぐ
• ソースコードを再解析する必要はない — すべてがproject.dbにインデックス付けされている

📚 ドキュメント

ディレクティブリファレンス

すべてのディレクティブドキュメントは、パッケージに同梱されています src/aifp/reference/directives/ — 129個のMDファイルがすべてのディレクティブをカバーしています。各ファイルには、目的、適用時期、完全なワークフロー（トランク → ブランチ）、準拠/非準拠の例、エッジケース、関連するディレクティブ、使用されるヘルパー関数、およびデータベース操作が含まれています。

データベーススキーマ

スキーマSQLファイルは、パッケージ内のsrc/aifp/database/schemas/にあります：

• aifp_core.sql — グローバルな読み取り専用データベース（ディレクティブ、ヘルパー、フロー）
• project.sql — プロジェクトごとの可変データベース（ファイル、関数、タスク、マイルストーン）
• user_preferences.sql — プロジェクトごとのユーザーカスタマイズデータベース
• user_directives.sql — プロジェクトごとの自動化ディレクティブ（ユースケース2のみ）

🔧 技術詳細

コア原則

1. 関数型 - 手続き型ハイブリッド

# ✅ AIFP準拠
from typing import List
from functools import reduce

class Item:
    def __init__(self, price):
        self.price = price

def calculate_total(items: List[Item]) -> float:
    """純粋な関数: 決定論的で副作用がない"""
    return reduce(lambda acc, item: acc + item.price, items, 0.0)

# ❌ AIFP非準拠
class Calculator:
    def __init__(self):
        self.total = 0  # 隠れた状態

    def add_item(self, item):
        self.total += item.price  # 変更

2. データベース索引付きロジック

すべての関数、ファイル、および依存関係はSQLiteで追跡されます。AIはヘルパーツールを通じてこのデータにアクセスします — 生のSQLではありません：

AI呼び出し: get_functions_by_file(project_root, file_id)
→ 戻り値: そのファイル内のすべての関数（名前、目的、行番号、依存関係）

ソースコードを再解析する必要はなく、セッションをまたいで即座にコンテキストを取得できます。

3. AI読み取り可能なコード

• フラットな構造：深い継承階層はありません。
• 明示的な依存関係：すべてのパラメータは明示的に渡されます。
• 純粋な関数：同じ入力 → 同じ出力。
• メタデータ注釈：機械読み取り可能な関数ヘッダー。

4. 有限の完了パス

プロジェクト: MatrixCalculator
├── 完了パス (3段階)
│   ├── 1. セットアップ (完了)
│   ├── 2. コア開発 (進行中)
│   │   ├── マイルストーン: 行列演算
│   │   │   ├── タスク: multiplyの実装
│   │   │   ├── タスク: transposeの実装
│   │   │   └── タスク: 検証の追加
│   │   └── マイルストーン: ベクトル演算
│   └── 3. 最終化 (未実施)

5. 言語非依存

AIFPはPython、JavaScript、TypeScript、Rust、Goなどで動作します。FPディレクティブは、言語固有の構文に適応しながら、普遍的な標準を維持します。

アーキテクチャの概要

┌─────────────────────────────────────────────────────┐
│            AIアシスタント (Claude, GPT-4など)        │
│  - 自然言語コマンドを受け取る                        │
│  - ディレクティブに従う (FPベースライン + プロジェクト管理)   │
│  - MCPツールを呼び出してデータベースを読み書きする       │
│  - FP準拠のコードを生成する                         │
└────────────────────┬────────────────────────────────┘
                     │ MCPプロトコル (JSON-RPC over stdio)
┌────────────────────▼────────────────────────────────┐
│                 MCPサーバー                           │
│  - JSON-RPCを介してヘルパーツールを公開する           │
│  - 4つのデータベース接続を管理する                   │
│  - すべてのデータベースに対するCRUDヘルパーを提供する   │
│  - ビジネスロジックはない — AIがすべての決定を行う      │
└───┬────────────────────┬─────────────────────────┬──┘
    │                    │                         │
┌───▼──────────────┐ ┌───▼────────────────┐ ┌─────▼─────────────────┐ ┌──────▼────────────────┐
│  aifp_core.db    │ │  project.db        │ │  user_preferences.db  │ │  user_directives.db   │
│  (グローバル、    │ │  (プロジェクトごと、 │ │  (プロジェクトごと、    │ │  (プロジェクトごと、    │
│   読み取り専用)   │ │   可変)           │ │   可変)            │ │   オプション)           │
│                  │ │                    │ │                       │ │                       │
│ - FPディレクティブ  │ │ - プロジェクトメタデータ │ │ - ディレクティブ設定     │ │ - ユーザーディレクティブ   │
│ - プロジェクト管理   │ │ - ファイルと関数    │ │ - ユーザー設定       │ │ - 実行統計       │
│ - ユーザー設定     │ │ - タスク階層       │ │ - AI学習ログ       │ │ - 依存関係        │
│ - ユーザーシステム   │ │ - テーマとフロー   │ │ - トラッキング機能   │ │ - 生成されたコード参照 │
│ - ヘルパー定義    │ │ - 完了パス        │ │ (すべてオプトイン)    │ │ - ソースファイル追跡│
│ - ディレクティブフロー │ │ - ランタイムノート    │ │                       │ │ (ファイル内のログ)       │
└──────────────────┘ └────────────────────┘ └───────────────────────┘ └───────────────────────┘

データベースアーキテクチャ

aifp_core.db (グローバル、読み取り専用)

場所：MCPサーバーのインストールディレクトリ内（ユーザー定義の場所、AIクライアントで設定）

目的：すべてのAIFP標準、ディレクティブ、およびヘルパー定義を含む不変の知識ベース。

主要なテーブル：

• directives：すべてのFP、プロジェクト、およびユーザー設定ディレクティブ（ワークフロー、キーワード、しきい値）
• helper_functions：データベース、ファイル、Git、およびFPユーティリティが複数のレジストリファイルにまたがって整理されている
• directive_helpers：多対多のジャンクションテーブル ディレクティブをそのヘルパー関数に実行メタデータとともにマッピングする
• directives_interactions：クロスディレクティブの関係と依存関係
• categories：ディレクティブのグルーピング（純度、不変性、タスク管理など）
• tools：MCPツールの定義

ヘルパー - ディレクティブの関係 （v1.4で新規）：

• 1つのディレクティブは複数のヘルパーを使用でき、1つのヘルパーは複数のディレクティブにサービスできる
• ジャンクションテーブルには、実行コンテキスト、シーケンス順序、パラメータマッピングが格納される
• 柔軟なヘルパーの再利用と明確な実行フローを可能にする
• aifp_core.dbのdirective_helpersジャンクションテーブルで定義される

ヘルパーの分類：

• ツール：すべてのヘルパーはMCPツールとして公開される（AIはMCPを介して直接呼び出す）
• サブヘルパー (is_sub_helper = TRUE)：他のヘルパーによってのみ呼び出される内部ユーティリティ（AIに公開されない）

ヘルパーレジストリ （開発段階）：

• 開発中は、docs/helpers/json/*.jsonでヘルパー定義が維持される
• 開発者がJSONファイルを修正し、完了したらデータベースにインポートする
• 各ヘルパーには、関係マッピングのためのused_by_directivesフィールドが含まれる
• データベースインポートスクリプトは、リリース前にJSONファイルからaifp_core.dbをポピュレートする
• 本番環境では、ユーザーはaifp_core.db（事前にポピュレートされた）をクエリし、JSONファイルではない
• JSONファイルは開発専用のステージングエリアであり、パッケージには含まれない

読み取り専用の哲学：このデータベースはバージョン管理され、デプロイされると不変になります。AIはこれを読み取りますが、決して変更しません。

project.db (プロジェクトごと、可変)

場所：<project-root>/.aifp-project/project.db

目的：単一のAIFPプロジェクトの永続的な状態を追跡します。コード構造、タスク、およびランタイムノートを追跡します。

主要なテーブル：

• project：高レベルのメタデータ（名前、目的、目標、ステータス、user_directives_status、最後に知られているGitハッシュ）
• files, functions, interactions：コード構造の追跡
• themes, flows：組織的なグルーピング
• completion_path, milestones, tasks, subtasks, sidequests：階層的なロードマップ
• notes：オプションのディレクティブコンテキスト（ソース、重大度、ディレクティブ名）を持つランタイムロギング
• types：代数的データ型（ADTs）
• infrastructure：プロジェクトのセットアップ（言語、パッケージ、テスト）
• work_branches：Gitコラボレーションのメタデータ（ユーザー、目的、マージ戦略）
• merge_history：FPベースのマージコンフリクト解決の監査証跡

ユーザーディレクティブの統合：project.user_directives_statusフィールドは、ユーザーディレクティブが初期化されているかどうか（NULL/進行中/アクティブ/無効）を追跡し、aifp_runおよびaifp_statusディレクティブがアクティブなときにユーザーディレクティブのコンテキストを含めることができます。

拡張されたノート：notesテーブルには、現在source（ユーザー/AI/ディレクティブ）、directive_name（オプションのコンテキスト）、およびseverity（情報/警告/エラー）が含まれており、トレーサビリティが向上しています。

user_preferences.db (プロジェクトごと、可変)

場所：<project-root>/.aifp-project/user_preferences.db

目的：ユーザー固有のAI動作のカスタマイズとオプトインのトラッキング機能を提供します。

主要なテーブル：

• directive_preferences：ディレクティブごとの動作オーバーライド（原子的なキー値構造）
• user_settings：プロジェクト全体のAI動作設定
• tracking_settings：オプトインのトラッキングの機能フラグ（デフォルトですべて無効）
• ai_interaction_log：ユーザーの修正と学習データ（オプトイン）
• fp_flow_tracking：FP準拠の履歴（オプトイン）
• issue_reports：コンテキスト付きのバグレポート（オプトイン）

コスト管理の哲学：すべてのトラッキング機能はデフォルトで無効になっており、APIトークンの使用を最小限に抑えます。プロジェクト作業はコスト効率が良くなければならず、デバッグと分析はオプトインです。

ユーザーカスタマイズの例：

-- ユーザーが言う: "常にドキュメント文字列を追加する"
INSERT INTO directive_preferences (directive_name, preference_key, preference_value)
VALUES ('project_file_write', 'always_add_docstrings', 'true');

-- 次のファイル書き込みで自動的にドキュメント文字列が含まれる

user_directives.db (プロジェクトごと、オプション)

場所：<project-root>/.aifp-project/user_directives.db

目的：ユーザー定義のドメイン固有のディレクティブを自動化のために保存します（ホームオートメーション、クラウドインフラストラクチャなど）。 このデータベースが存在する場合、AIFPプロジェクトはこれらのディレクティブから生成された自動化コードベースの構築と管理に専念します。

このデータベースは、ユースケース2: カスタムディレクティブ自動化 プロジェクトでのみ存在します。通常のソフトウェア開発プロジェクトでは、このデータベースは作成されません。

主要なテーブル：

• user_directives：ディレクティブの定義（トリガー、アクション、ステータス、検証済みの構成）
• directive_executions：実行統計（概要のみ、詳細なログはファイルに保存）
• directive_dependencies：必要なパッケージ、API、環境変数
• directive_implementations：ディレクティブを生成されたコードファイルにリンクする
• helper_functions：AIによって生成されたヘルパー関数 （プロジェクト固有の実装ユーティリティ）
• directive_helpers：多対多のジャンクションテーブル ユーザーディレクティブをそのヘルパーにマッピングする
• source_files：ユーザーディレクティブのソースファイル（YAML/JSON/TXT）を追跡する
• logging_config：ファイルベースのロギング構成

ヘルパー関数 （v1.0で新規）：

• AIはユーザーディレクティブのためにプロジェクト固有のヘルパー関数を生成します
• 実装ステータスで追跡されます：未実装 → 生成済み → テスト済み → 承認済み
• すべての生成されたコードに対してFP準拠を強制します（純粋な関数）
• aifp_core.dbと同じ多対多の関係パターンを持ちます

ファイルベースのロギングの哲学：データベースは状態と統計のみを保存します。詳細な実行ログ（30日間の保持）とエラーログ（90日間の保持）は、.aifp-project/logs/のローテーティングファイルに保存されます。

ディレクトリ構造の比較：

# ユースケース1: 通常のソフトウェア開発
my-web-app/
├── src/                    # あなたのアプリケーションコード
├── tests/                  # あなたのテスト
└── .aifp-project/          # AIFPがあなたのアプリケーションを追跡する
    ├── project.db
    └── user_preferences.db

# ユースケース2: カスタムディレクティブ自動化
home-automation/
├── directives/             # ← ユーザーがディレクティブファイルをここに書く
│   ├── lights.yaml
│   └── security.yaml
├── src/                    # ← AIFPがこのコードを生成する
│   ├── lights_controller.py
│   └── security_monitor.py
├── tests/                  # ← AIFPがテストを生成する
└── .aifp-project/          # ← AIによってのみ管理され、ユーザーは触れない
    ├── project.db          # 生成されたsrc/コードを追跡する
    ├── user_preferences.db
    ├── user_directives.db  # ../directives/ファイルを参照する
    └── logs/               # 30/90日間の実行ログ

例のワークフロー（自動化プロジェクト）：

1. ユーザーがプロジェクト内にdirectives/lights.yamlを作成する
2. ユーザーがAIに言う: "Parse my directive file at directives/lights.yaml"
3. AIが対話型の質問と回答を通じて解析と検証を行う
4. AIがsrc/にFP準拠の実装コードを生成する
5. AIがproject.dbに生成されたコードを追跡する（ファイル、関数、タスク）
6. ディレクティブがバックグラウンドサービスを介してリアルタイムで実行される
7. 実行ログが.aifp-project/logs/に、統計がデータベースに保存される

注意：ユーザーディレクティブファイルはユーザーのプロジェクト内に残ります。.aifp-project/はAIによって管理されるメタデータです。

動作の仕方

1. AIFP MCPゲートウェイパターン

aifp_runコマンドは、ゲートウェイとリマインダー として機能し、実行者ではありません。これは、AIFPディレクティブを適用する必要があることをAIに伝えます。

すべてのaifp_run呼び出しは次を返します：

{
  "success": true,
  "message": "AIFP MCP available",
  "guidance": {
    "directive_access": "Directive names cached from session bundle. Query specific directives by name when needed.",
    "when_to_use": "Use AIFP directives when coding or when project management action/reaction is needed.",
    "assumption": "Always assume AIFP applies unless user explicitly rejects it."
  }
}

MCPサーバーは、すべてのデータベース操作（ファイル、関数、タスク、プロジェクト状態、ユーザー設定、および（ユースケース2の場合）自動化ディレクティブの追跡）に対するCRUDヘルパー関数を公開します。AIは実行時にデータベースから利用可能なヘルパーを発見します。

AIの決定フロー：

1. ユーザーがリクエストにaifp runを付ける（またはAIが自動的に想定する）
2. AIがaifp_runツールを呼び出す → ガイダンスを受け取る
3. AIが評価する: これはコーディングまたはプロジェクト管理ですか？
4. もしそうなら: ディレクティブがメモリにあるかチェックする
   • ディレクティブがない場合 → get_all_directives()を呼び出す
   • ディレクティブがある場合 → 適切なものを適用する
5. そうでない場合: ディレクティブを使用せずに応答する

2. コマンドフローの例

ユーザー: "Help me build a calculator"

AIの処理：

1. aifp_run(is_new_session=true)を呼び出す → セッションバンドル（ディレクティブ名、プロジェクトステータス、設定、サポートコンテキスト）を受け取る
2. バンドルからプロジェクトの状態をチェックする: .aifp-project/がない → プロジェクトが初期化されていない
3. aifp_initヘルパーを呼び出す（フェーズ1: 機械的なセットアップ）
   • プログラム的に.aifp-project/ディレクトリ、データベース、ブループリントテンプレートを作成する
4. フェーズ2（インテリジェントなポピュレーション）に入る: 言語/ツールを検出し、ユーザーとプロジェクトについて話し合う
5. project_discoveryにルーティングする: ユーザーとブループリント、テーマ、フロー、完了パス、マイルストーンについて協力する
6. ディスカバリーが完了する → aifp_status → project_progression → 最初のタスクが作成される
7. 作業を開始する

3. 自己評価フレームワーク

行動する前に、AIはディレクティブとともに提供される質問を使用して自己評価を行います：

コア質問：

1. これはコーディングまたはプロジェクト状態の変更に関係しますか？

   • コーディングとプロジェクト管理は統一されています — コードを書くと、ファイルの追跡、DBの更新、およびタスクの進行が自動的にトリガーされます
   • FPベースラインは常に必須のコーディングスタイルとしてアクティブです
   • プロジェクトディレクティブは、追跡の側面（ファイルの書き込み、DBの更新、タスクの管理）を処理します

2. メモリにディレクティブがありますか？

   • いいえ: aifp_run(is_new_session=true)を介してセッションバンドルからロードする
   • はい: キャッシュされたディレクティブで進める

3. どのディレクティブが適用されますか？

   • FPベースライン: 必須のコーディングスタイル（純粋な関数、不変性、OOPなし） — 自然に適用され、ディレクティブ呼び出しとしてではない
   • FPディレクティブ: 参考ドキュメントのみ — 複雑なシナリオで不確かな場合に参照される
   • プロジェクトディレクティブ: ファイルの書き込み、DBの更新、タスクの管理

4. アクション - 反応が必要ですか？

   • コードの書き込み → project_file_writeディレクティブ → DBの更新
   • ファイルの編集 → DBの同期
   • 決定を伴う議論 → DBの更新

例のフロー（コーディングタスク）：

ユーザー: "Write multiply_matrices function"
AIが考える:
  ✓ FPベースラインが適用されます（純粋で不変、OOPなしで書く）
  ✓ プロジェクトの追跡が適用されます（project_file_writeディレクティブ）
  ✓ メモリにディレクティブがあります

AIが実行する:
  1. FPベースラインに従って自然に関数を書く
  2. project_file_writeディレクティブを適用する
  3. project.dbを更新する（ファイル、関数、相互作用）

4. ディレクティブの実行

ディレクティブは、トランク → ブランチ → フォールバック のパターンに従います：

{
  "trunk": "analyze_function",
  "branches": [
    {"if": "pure_function", "then": "mark_compliant"},
    {"if": "mutation_detected", "then": "refactor_to_pure"},
    {"if": "low_confidence", "then": "prompt_user"},
    {"fallback": "prompt_user"}
  ]
}

ディレクティブシステム

FPベースラインとFPディレクティブ

FPベースライン （常にアクティブ）：

• AIがコードを書くときに自然に従うコア関数型プログラミングルール
• 純粋な関数、不変性、OOPなし、明示的なエラーハンドリング
• 交渉不能 — すべてのコードはFP準拠でなければならない

FPディレクティブ （参考ドキュメント）：

• 複雑なシナリオやエッジケースに対する詳細なガイダンス
• AIが実装について不確かな場合にのみ参照される
• カテゴリ: 純度、合成、エラーハンドリング、OOPの排除、最適化
• 例: fp_purity, fp_monadic_composition, fp_result_types, fp_wrapper_generation

プロジェクトディレクティブ

プロジェクトのライフサイクルを管理します：

ユーザー設定ディレクティブ

AIの動作のカスタマイズと学習を管理します：