aifp

AIMFP：AI モジュール型関数型手続き型プログラミング

AI によって生成・保守されるコードベース向けに設計された、言語に依存しないプログラミングパラダイム

---

目次

• AIMFP とは？
• 基本原則
• アーキテクチャの概要
• データベースアーキテクチャ
• 仕組み
• はじめに
• プラットフォームのサポート
• ディレクティブシステム
• プロジェクトのライフサイクル
• ワークフローの例
• ドキュメント
• 開発
• 設計思想
• 機能
• 使用例
• プライバシーポリシー
• サポート
• ライセンス

---

AIMFP とは？

**AIMFP（AI モジュール型関数型手続き型）**は、以下を組み合わせたプログラミングパラダイムです。

• 純粋関数型プログラミングの原則（参照透過性、不変性、合成可能性）
• 手続き型の実行パターン（明示的な順序指定、隠れた状態なし）
• データベース駆動のプロジェクト管理（永続化された状態、即時のコンテキスト取得）
• ディレクティブベースの AI ガイダンス（決定論的なワークフロー、自動化された準拠管理）

AIMFP の 2 つの利用方法

ユースケース 1：通常のソフトウェア開発

• アプリケーションを構築します（ウェブアプリ、ライブラリ、CLI ツールなど）
• AIMFP が FP への準拠を徹底し、プロジェクトを管理します
• コードを書くのはあなたで、AI は FP 標準への準拠とプロジェクトの追跡を支援します
• 例：ウェブサーバー、計算ライブラリ、データプロセッサーの構築

ユースケース 2：カスタムディレクティブによる自動化

• 自動化ルールを定義します（ホームオートメーション、クラウド管理、ワークフロー）
• AIMFP が自動化コードベースを生成し、管理します
• ディレクティブの定義（YAML/JSON/TXT）を記述すると、AI が実装を生成します
• プロジェクトのコードは、ディレクティブから生成された自動化コードそのものです
• 例：スマートホーム制御システム、AWS インフラストラクチャマネージャー、ワークフロー自動化ツール

重要な原則：プロジェクトディレクトリごとに AIMFP インスタンスを 1 つ使用します。ウェブアプリとホームオートメーションのディレクティブを混在させることはありません。目的ごとに別々のインスタンスを実行してください。

AIMFP を選ぶ理由

従来のプログラミングパラダイムは人間向けに設計されていました。AIMFP はAI と人間の協働に最適化されています。

課題	従来のアプローチ	AIMFP のソリューション
コンテキストの喪失	AI はセッション間で内容を忘れる	データベース駆動の永続化された状態
OOP の複雑さ	クラス、継承、ポリモーフィズム	純粋関数、明示的なデータ構造
終わりのない開発	プロジェクトがいつまでも「完了」しない	マイルストーンを伴う有限の完了パス
コードの推論	ソースコードを繰り返し解析する	関数、依存関係、相互作用の事前インデックス化
一貫しない標準	スタイルガイド、リンター、レビュー	準拠を徹底する不変のディレクティブ

---

基本原則

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

# ✅ AIMFP-Compliant
def calculate_total(items: List[Item]) -> float:
    """Pure function: deterministic, no side effects"""
    return reduce(lambda acc, item: acc + item.price, items, 0.0)

# ❌ Not AIMFP-Compliant
class Calculator:
    def __init__(self):
        self.total = 0  # Hidden state

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

2. データベースでインデックス化されたロジック

すべての関数、ファイル、依存関係を SQLite で追跡します。AI は生の SQL ではなく、ヘルパーツールを通じてこのデータにアクセスします。

AI calls: get_functions_by_file(file_id)
→ Returns: all functions in that file with name, purpose, parameters, returns

ソースコードを再解析する必要はありません。セッションをまたいで、コンテキストをすぐに取得できます。

3. AI が読み取りやすいコード

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

4. 有限の完了パス

Project: MatrixCalculator
├── Completion Path (3 stages)
│   ├── 1. Setup (completed)
│   ├── 2. Core Development (in progress)
│   │   ├── Milestone: Matrix Operations
│   │   │   ├── Task: Implement multiply
│   │   │   ├── Task: Implement transpose
│   │   │   └── Task: Add validation
│   │   └── Milestone: Vector Operations
│   └── 3. Finalization (pending)

5. 言語に依存しない

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

---

アーキテクチャの概要

┌─────────────────────────────────────────────────────┐
│            AI Assistant (Claude, GPT-4, etc.)        │
│  - Receives natural language commands                │
│  - Follows directives (FP baseline + project mgmt)   │
│  - Calls MCP tools to read/write databases           │
│  - Generates FP-compliant code                       │
└────────────────────┬────────────────────────────────┘
                     │ MCP Protocol (JSON-RPC over stdio)
┌────────────────────▼────────────────────────────────┐
│                 MCP Server                           │
│  - Exposes helper tools via JSON-RPC                  │
│  - Manages four-database connections                 │
│  - Provides CRUD helpers for all databases           │
│  - No business logic — AI makes all decisions        │
└───┬────────────────────┬─────────────────────────┬──┘
    │                    │                         │
┌───▼──────────────┐ ┌───▼────────────────┐ ┌─────▼─────────────────┐ ┌──────▼────────────────┐
│  aimfp_core.db    │ │  project.db        │ │  user_preferences.db  │ │  user_directives.db   │
│  (Global,        │ │  (Per-Project,     │ │  (Per-Project,        │ │  (Per-Project,        │
│   Read-Only)     │ │   Mutable)         │ │   Mutable)            │ │   Optional)           │
│                  │ │                    │ │                       │ │                       │
│ - FP directives  │ │ - Project metadata │ │ - Directive prefs     │ │ - User directives     │
│ - Project mgmt   │ │ - Files & funcs    │ │ - User settings       │ │ - Execution stats     │
│ - User prefs     │ │ - Task hierarchy   │ │ - AI learning log     │ │ - Dependencies        │
│ - User systems   │ │ - Themes & flows   │ │ - Tracking features   │ │ - Generated code refs │
│ - Helper defs    │ │ - Completion path  │ │ (All opt-in)          │ │ - Source file tracking│
│ - Directive flow │ │ - Runtime notes    │ │                       │ │ (Logs in files)       │
└──────────────────┘ └────────────────────┘ └───────────────────────┘ └───────────────────────┘

ユースケース 2 では、MCP サーバーを一切経由しない 2 つ目の経路を追加します。 AI セッションが開いていないときにも自動化を実行する必要があるため、代わりに AIMFP を通常のライブラリとしてインポートします。

┌──────────────────────────────┐        ┌──────────────────────────────┐
│  cron / systemd / your daemon │        │  AI Assistant (a session)     │
│  runs forever; AIMFP does not │        │  present only when you are    │
└───────────────┬──────────────┘        └───────────────┬──────────────┘
                │ starts                                 │ MCP
┌───────────────▼──────────────┐        ┌───────────────▼──────────────┐
│  runner.py  (YOUR project)    │        │         MCP Server            │
│  generated by AIMFP, owned    │        │                               │
│  and editable by you          │        │  check_directive_health       │
│                               │        │  get_directive_execution_stats│
│  import aimfp.hooks  ◄────────┼── a    │  get_recent_directive_errors  │
│  get_due_directives(...)      │  library                              │
│  run_directive(...)           │  call, └───────────────┬──────────────┘
└───────────────┬──────────────┘  not RPC               │ reads
                │ writes                                 │
                └────────────►  user_directives.db  ◄────┘
                                + .aimfp-project/logs/

ランナーが書き込み、AI は後でそれを読み取ります。その間、AIMFP 自体は動作せず、タイマーもなく、何も開始しません。

---

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

aimfp_core.db（グローバル、読み取り専用）

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

目的：AIMFP のすべての標準、ディレクティブ、ヘルパー定義を含む不変のナレッジベースです。

主要なテーブル：

• directives：すべての FP、プロジェクト、ユーザー設定のディレクティブ（ワークフロー、キーワード、しきい値）
• helper_functions：複数のレジストリファイルに整理された、データベース、ファイル、Git、FP のユーティリティ
• directive_helpers：ディレクティブと、それに対応するヘルパー関数を実行メタデータとともにマッピングする多対多の中間テーブル
• categories：ディレクティブのグループ（純粋性、不変性、タスク管理など）
• directive_flow：ステータスに基づくディレクティブのナビゲーションとルーティング

ヘルパーとディレクティブの関係（v1.4 の新機能）：

• 1 つのディレクティブで複数のヘルパーを利用でき、1 つのヘルパーを複数のディレクティブで利用できます
• 中間テーブルには、実行コンテキスト、順序、パラメーターのマッピングが保存されます
• ヘルパーを柔軟に再利用でき、実行フローを明確にできます
• aimfp_core.db の directive_helpers 中間テーブルで定義されています

ヘルパーの分類：

• ツール：すべてのヘルパーは MCP ツールとして公開されます（AI が MCP 経由で直接呼び出します）
• サブヘルパー（is_sub_helper = TRUE）：他のヘルパーのみが呼び出す内部ユーティリティ（AI には公開されません）

ヘルパーレジストリ（開発用ステージング）：

• 開発中、ヘルパー定義は dev/helpers-json/*.json で管理されます
• 開発者は JSON ファイルを変更し、完成したらデータベースにインポートします
• 各ヘルパーには、関係のマッピングに使用する used_by_directives フィールドが含まれます
• リリース前に、データベースのインポートスクリプトが JSON ファイルから aimfp_core.db にデータを登録します
• 本番環境では、ユーザーは JSON ファイルではなく、データがあらかじめ登録された aimfp_core.db を参照します
• JSON ファイルは開発専用のステージング領域であり、パッケージには含まれません

読み取り専用の方針：このデータベースはバージョン管理され、デプロイ後は不変です。AI はここから読み取りますが、変更することはありません。

project.db（プロジェクトごと、変更可能）

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

目的：単一の AIMFP プロジェクトの永続状態を保持します。コード構造、タスク、実行時のメモを追跡します。

主要なテーブル：

• project：上位レベルのメタデータ（名前、目的、目標、ステータス、user_directives_status、last_known_git_hash）
• files、functions、interactions：コード構造の追跡
• themes、flows：組織上のグループ分け
• completion_path、milestones、tasks、subtasks、sidequests、items：階層型ロードマップ
• task_files：各タスク／サブタスク／サイドクエストで作業したファイル。項目が進行中の間、自動的に関連付けられます
• modules、module_files、file_flows：再利用可能なコード境界とファイルからフローへの割り当て
• notes：任意のディレクティブコンテキスト（source、severity、directive_name）を含む実行時ログ
• types：代数的データ型（ADT）
• infrastructure：プロジェクトのセットアップ（言語、パッケージ、テスト）
• work_branches：Git コラボレーションのメタデータ（ユーザー、目的、マージ戦略）
• merge_history：FP を活用したマージコンフリクト解決の監査証跡

ユーザーディレクティブとの統合：project.user_directives_status フィールドは、ユーザーディレクティブが初期化されているかどうか（NULL/in_progress/active/disabled）を追跡します。これにより、有効な場合、aimfp_run および aimfp_status ディレクティブにユーザーディレクティブのコンテキストを含められます。

拡張されたメモ：追跡性を高めるため、notes テーブルに source（user/ai/directive）、directive_name（任意のコンテキスト）、severity（info/warning/error）が追加されました。

user_preferences.db（プロジェクトごと、変更可能）

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

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

主なテーブル：

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

コスト管理の方針：API トークンの使用量を最小限に抑えるため、すべてのトラッキング機能はデフォルトで無効です。プロジェクト作業はコスト効率を重視し、デバッグと分析はオプトイン方式です。

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

-- User says: "Always add docstrings"
INSERT INTO directive_preferences (directive_name, preference_key, preference_value)
VALUES ('project_file_write', 'always_add_docstrings', 'true');

-- Next file write automatically includes docstrings

user_directives.db（プロジェクトごと、任意）

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

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

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

主なテーブル：

• user_directives：ディレクティブの定義（トリガー、アクション、ステータス、検証済みの設定）。trigger_config と action_config には文法上の制約があります。詳しくはディレクティブ設定スキーマを参照してください。
• directive_executions：実行統計（概要のみ。詳細ログはファイルに保存）
• directive_dependencies：必要なパッケージ、API、環境変数
• directive_implementations：ディレクティブと生成されたコードファイルの関連付け
• helper_functions：AI が生成したヘルパー関数（プロジェクト固有の実装ユーティリティ）
• directive_helpers：多対多の中間テーブル。ユーザーディレクティブとそのヘルパーを関連付けます。
• source_files：ユーザーディレクティブのソースファイル（YAML/JSON/TXT）を追跡します。
• logging_config：ファイルベースのログ設定

ヘルパー関数（v1.0 で追加）：

• AI がユーザーディレクティブ用にプロジェクト固有のヘルパー関数を生成します。
• 実装ステータスを追跡します：not_implemented → generated → tested → approved
• 生成されたすべてのコードで FP 準拠（純粋関数）を徹底します。
• aimfp_core.db と同じ多対多の関連付けパターンを使用します。

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

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

# Use Case 1: Regular Software Development
my-web-app/
├── src/                    # Your application code
├── tests/                  # Your tests
└── .aimfp-project/          # AIMFP tracks your application
    ├── project.db
    └── user_preferences.db

# Use Case 2: Custom Directive Automation
home-automation/
├── directives/             # ← User writes directive files here
│   ├── lights.yaml
│   └── security.yaml
├── src/                    # ← AIMFP GENERATES this code
│   ├── lights_controller.py
│   ├── security_monitor.py
│   └── runner.py           # ← the RUNNER: your scheduler calls this,
│                           #    it imports aimfp.hooks as a library
├── tests/                  # ← AIMFP GENERATES tests
└── .aimfp-project/          # ← AI-managed only, user never touches
    ├── project.db          # Tracks generated src/ code
    ├── user_preferences.db
    ├── user_directives.db  # References ../directives/ files
    └── logs/               # 30/90-day execution logs

# ...and outside the project entirely:
/etc/cron.d/home-automation  # ← what actually STARTS runner.py. Not AIMFP.

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

1. ユーザーがプロジェクト内に directives/lights.yaml を作成します。
2. ユーザーが AI に「directives/lights.yaml にあるディレクティブファイルを解析して」と伝えます。
3. AI が対話形式の質疑応答を通じて解析し、検証します。
4. AI が src/ に FP 準拠の実装コードを生成します。
5. AI が生成したコードを project.db（ファイル、関数、タスク）で追跡します。
6. AI がランナーを生成し、スケジューラー（cron、systemd、またはデーモンループ）に接続します。
7. スケジューラーがディレクティブを実行します。AIMFP にタイマー機能はなく、午前 3 時に実行されているわけではありません。
8. ランナーは aimfp.hooks を通じて各実行を記録します。ログは .aimfp-project/logs/ に、統計は user_directives.db に保存されます。
9. 次回のセッションで、AIMFP が実行結果と問題がありそうな箇所を報告します。

注：ユーザーディレクティブファイルはユーザーのプロジェクト内に置かれます。.aimfp-project/ は AI が管理するメタデータです。

ディレクティブ設定スキーマ

トリガーとアクションには厳格な文法が適用されます。適合しない設定は挿入時に拒否されます。不正なアクションは実行時にエラーとして明確に通知されますが、不正なスケジュールは一度も発火せず、黙って失敗します。そのため、どちらも保存前にチェックされます。

トリガー — 時刻トリガーは kind による判別共用体です。

{"kind": "interval", "seconds": 900}
{"kind": "daily",    "at": "17:00", "timezone": "America/New_York"}
{"kind": "weekly",   "at": "17:00", "weekdays": ["mon","wed","fri"]}
{"kind": "monthly",  "at": "09:00", "days": [1, 15]}

{"event": "stove_on", "source": "home_assistant"}              // event
{"expression": "cpu > 90", "evaluate_every_seconds": 60}       // condition (fires once per rise)
{"expression": "cpu > 90", "repeat": "while_true"}             // condition (fires every true check)
{}                                                             // manual

at はゼロ埋めの24時間表記 HH:MM です。timezone は IANA 名で、経過秒数を数える interval では有効ではありません。不明なキーはエラーになります。スケジュールのキーにタイプミスがあっても、そうしなければ検証を通過し、その後一度も発火しないためです。

アクション — action_type ごとのエンベロープです。

{"endpoint": "/lights/off", "api": "homeassistant", "method": "POST"}  // api_call
{"script": "scripts/backup.sh", "args": ["--full"]}                    // script_execution
{"command": "systemctl restart nginx"}                                 // command
{"function": "handlers.lights.turn_off"}                               // function_call
{"message": "Backup finished", "channel": "ops"}                       // notification

function_call と command について、AIMFP が検証するのはエンベロープのみです。関数や実行ファイルは生成されたプロジェクトに存在するため、実際に解決できるかどうかはご自身で確認してください。

スケジュールの計算も AIMFP が担当します。aimfp.hooks.schedule.next_fire_time は次回の実行時刻を計算し（DST の境界をまたいでも壁時計時刻を正しく処理します）、record_execution_end は各実行後に next_scheduled_time を自動的に更新します。ランナーがカレンダー計算を独自に実装する必要はありません。そうしないと、17:00 がいつなのかについて、2つのプロジェクトで食い違うことになります。

UI を作成する場合に知っておくべき点があります。next_scheduled_time はローカル時刻としてタイムゾーン情報なしで保存されます。これは、is_due がタイムゾーン情報のないローカルの現在時刻と比較するためです。America/New_York の 17:00 として宣言されたスケジュールは、ロサンゼルスのマシンでは 14:00 として保存されます。宣言されたタイムゾーンは trigger_config に保持されているため、情報が失われることはありません。ただし、このカラムは比較用の値であり、表示用ではありません。ユーザーにスケジュールを表示するには、必ず trigger_config を使い、next_scheduled_time は使わないでください。そうしないと、すでに正しい設定をユーザーが「修正」してしまいます。

AIMFP は条件を評価しませんが、文法では条件が保持されている場合にどの頻度で発火するかを定めています。デフォルトでは、条件は真になったときに一度だけ発火し、評価結果が偽になると再び発火可能になります。"repeat": "while_true" を指定すると、真と評価されるたびに発火します。ランナーは set_condition_state でこのラッチ状態を保持するため、条件が真のままでも再起動によって再発火することはありません。ランナーが到達するのが遅すぎた時刻枠は、補完実行されず、スキップされ、record_directive_skip で記録されます。スキップは実行にもエラーにも数えられず、スキップが続くディレクティブは、誤って ok と報告されるのではなく skipping と報告されます。

AI は validate_trigger_config ツールと validate_action_config ツールで設定を検証します。これらのツールは、エラーがあればそれとともに期待される形式を返します。完全な仕様は、trigger_config_grammar() フックと action_config_grammar() フックからデータとして取得できます。

---

仕組み

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

aimfp_run コマンドは、実行機能ではなくゲートウェイ兼リマインダーとして機能します。AIMFP のディレクティブを適用する必要があることを AI に伝えます。

aimfp_run を呼び出すたびに返される内容：

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

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

AI の判断フロー：

1. ユーザーがリクエストの前に aimfp run を付けます（または AI がそう判断します）
2. AI が aimfp_run ツールを呼び出し、ガイダンスを受け取ります
3. AI が判断します。この依頼はコーディングですか、それともプロジェクト管理ですか？
4. 該当する場合：ディレクティブがメモリ内にあるか確認します
   • ディレクティブがない場合？→ ディレクティブ名はセッションバンドルからキャッシュされています。必要に応じて名前で照会します
   • ディレクティブがある場合？→ 適切なものを適用します
5. 該当しない場合：ディレクティブを使わずに応答します

2. コマンドフローの例

User: "Help me build a calculator"

AI の処理:

1. aimfp_run(is_new_session=true) を呼び出し → セッションバンドル（ディレクティブ名、プロジェクトの状態、設定、補助コンテキスト）を受け取ります
2. バンドルからプロジェクトの状態を確認：.aimfp-project/ がない → プロジェクトは未初期化です
3. aimfp_init ヘルパーを呼び出し（フェーズ 1：機械的なセットアップ）
   • .aimfp-project/ ディレクトリ、データベース、ブループリントのテンプレートをプログラムで作成します
4. フェーズ 2（インテリジェントな情報入力）に進み、言語やツールを検出して、ユーザーとプロジェクトについて話し合います
5. project_discovery にルーティングし、ユーザーと協力してブループリント、テーマ、フロー、完了までの道筋、マイルストーンを作成します
6. 検出が完了 → aimfp_status にルーティング → project_progression → 最初のタスクを作成します
7. 作業を開始します

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

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

主な質問:

1. コーディングまたはプロジェクトの状態変更が伴いますか？

   • コーディングとプロジェクト管理は統合されています。コードを書くと、ファイルの追跡、DB の更新、タスクの進行が自動的に行われます
   • FP のベースラインは、必須のコーディングスタイルとして常に有効です
   • プロジェクトのディレクティブが、追跡処理（ファイルへの書き込み、DB の更新、タスク管理）を担います

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

   • いいえ：aimfp_run(is_new_session=true) を使ってセッションバンドルから読み込みます
   • はい：キャッシュされたディレクティブを使います

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

   • FP のベースライン：必須のコーディングスタイル（純粋関数、不変性、OOP を使わない）— ディレクティブの呼び出しとしてではなく、自然に適用します
   • FP ディレクティブ：参照用ドキュメントのみ — 複雑な状況で判断に迷った場合に確認します
   • プロジェクトのディレクティブ：ファイルへの書き込み、DB の更新、タスク管理

4. アクションとリアクションが必要ですか？

   • コードの書き込み → project_file_write ディレクティブ → DB の更新
   • ファイルの編集 → DB の同期
   • 判断を伴う話し合い → DB の更新

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

User: "Write multiply_matrices function"
AI thinks:
  ✓ FP baseline applies (write pure, immutable, no OOP)
  ✓ Project tracking applies (project_file_write directive)
  ✓ I have directives in memory

AI executes:
  1. Write function following FP baseline naturally
  2. Apply project_file_write directive
  3. Update project.db (files, functions, interactions)

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"}
  ]
}

---

はじめに

前提条件

• Python 3.11 以降（全体で使用する型ヒント構文に必要です。開発とテストは 3.14 まで行っています）
• Linux — 下記のプラットフォームのサポートを参照してください

プラットフォームのサポート

AIMFP は Linux のみを対象に開発およびテストされています。コードベースのどこにもプラットフォーム条件分岐のコードがないため、Windows と macOS のサポートは未テストではなく、未構築です。これまで対応を試みたことはなく、動作させるには互換性の確認ではなく、実際の移植作業が必要です。

サーバーの中核部分は、原理上は移植可能です（標準ライブラリのみを使った stdio 経由の JSON-RPC、SQLite、pathlib）。そのため、一部がほかの環境でも動作する可能性はありますが、動作は検証されておらず、サポートもされていません。AIMFP を別のプラットフォームで実行する場合は、自己責任でお願いします。バグ報告は歓迎しますが、このプロジェクトが対象としている環境は Linux のみです。

インストール

AIMFP のインストール方法は 3 つあります。Claude Code では、プラグイン（方法 1）を使用してください。手動設定は不要で、コマンド 2 つでインストールできます。pip と手動インストールは、ほかの MCP クライアントや高度なセットアップ向けです。

方法 1：Claude Code プラグイン（Claude Code に推奨）

前提条件： PATH 上に uv があること（単体で動作するバイナリです）。このプラグインは uvx を使って MCP サーバーを起動します。uvx は公開済みの aimfp パッケージを PyPI から取得し、watchdog 依存関係を解決して、互換性のある Python（3.11 以降）を自動的に用意します。そのため、システムに一致するバージョンの Python や、別途 pip install を実行する必要はありません。

/plugin marketplace add aryanduntley/aimfp
/plugin install aimfp@aimfp

以上です。pip install も claude mcp add も設定ファイルも不要です。このプラグインには次のものが含まれます。

• MCP サーバー。uvx aimfp==<plugin version> で起動します。各プラグインリリースは対応する PyPI リリースを実行し、そのリリースは uvx にキャッシュされるため、初回起動後はオフラインでもサーバーが起動し、プラグインを更新すると新しいバージョンに切り替わります。
• スラッシュコマンド：/aimfp:run、/aimfp:status、/aimfp:init、/aimfp:end
• 小規模な aimfp-mode セットアップスキルと SessionStart フック。これらはセットアップ専用です。AI に対し、システムプロンプトをインストールし（get_system_prompt ツールを使用）、セッションを開始するよう促します。動作ルールを複製するものではありません（そうすると、すべてのセッションにシステムプロンプトが重複して含まれるためです）。インストール後の最初の手順は、引き続き AI に AIMFP システムプロンプトを追加するよう依頼することです。詳しくは、以下のシステムプロンプトを追加するを参照してください。プラグインの場合は AI が代わりに追加するため、ダウンロードや貼り付けは不要です。
• 書き込みの追跡を促すセッションフックと、セッション終了時の監査ガード

更新するには、/plugin marketplace update aimfp を実行してください。Anthropic アカウントも承認も中央レジストリも必要ありません。マーケットプレイスは、この公開 GitHub リポジトリです。

プラグインの MCP ツールにも、引き続きツールの事前承認が適用されます（ツール名は mcp__plugin_aimfp_aimfp__* です。許可リストは両方の命名方式に対応しています）。詳しくは、以下のすべての AIMFP ツールを事前承認するを参照してください。

プロジェクトごとに使用する方法は 1 つにしてください。 プロジェクトの .mcp.json にすでに aimfp サーバーが登録されている場合（方法 2／3）、プラグインをインストールすると 2 つ目の AIMFP サーバーが起動し、各ツールが 2 回ずつ表示されます（mcp__aimfp__* と mcp__plugin_aimfp_aimfp__*）。.mcp.json のエントリーを削除するか、そのプロジェクトでプラグインを有効にしないでください。

方法 2：pip install

pip install aimfp

これにより MCP サーバーがインストールされ、aimfp コマンドが使用できるようになります。AIMFP が必要とする外部依存関係は、ファイルシステム監視用の watchdog だけです。JSON-RPC サーバー自体は、Python 標準ライブラリのみで動作します。

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

1. リポジトリをダウンロードします（zip ファイルのダウンロードまたは git clone）。
2. src/aimfp/ フォルダーを確認します。これが MCP サーバーの完全なパッケージです。
3. aimfp/ フォルダーを、MCP サーバーを保管する場所にコピーします。

   # Example: copy to your MCP servers directory
   cp -r src/aimfp/ ~/mcp-servers/aimfp/
   

実行時の依存関係（watchdog）は自動的にインストールされます。aimfp/ フォルダーには、ヘルパー関数、ディレクティブ、データベーススキーマ、事前にデータが格納された aimfp_core.db など、サーバーに必要なその他すべてが含まれています。

システムプロンプトを追加する（最初に行うこと）

何よりも先に実行してください。 システムプロンプトは AIMFP の記録管理の要です。AI に最初に aimfp_run() を呼び出し、AIMFP を使ってプロジェクトを進めるよう指示します。これがないと、MCP ツールは呼び出されない受動的な関数にすぎず、AI は init やディスカバリーを開始する必要があることすら認識できません。

推奨 — プラグインを含むすべてのインストール方法で利用できます（ダウンロードや貼り付けは不要です）。 AI に次のように頼むだけです。

Add the AIMFP system prompt

AI が get_system_prompt ツールを呼び出すと、プロンプトと配置方法の案内が返され、AI が設定してくれます。

• プロジェクトのルートにある CLAUDE.md（Claude Code）、または Settings → Custom Instructions（Claude Desktop）に配置されます。
• AIMFP の内容が先頭に配置されます — プロジェクトの要であり、最優先の指示でなければならないためです。
• すでに詳細な CLAUDE.md／指示ファイルがある場合、AI がむやみに先頭へ追加することはありません。まず内容を確認して、統合や最適化について相談します。既存の内容が破棄されることはありません。
• 配置が完了すると、AI はツールの権限許可リストも設定するかどうかを確認します。これは、ツールごとの承認プロンプトを省略するための一度限りの手順です。事前に許可されるのは AIMFP 独自の CRUD ツールのみで、.aimfp-project/ の内部でのみ動作します。ネットワークへのアクセス、認証情報の使用、現在のプロジェクト外へのアクセスは行いません。

手動で設定する場合（その他の MCP クライアントを使う場合、または自分で貼り付けたい場合） — プロンプトを表示し、クライアントのシステムプロンプト／カスタム指示欄に貼り付けます。

python3 -m aimfp --system-prompt

AI クライアント	システムプロンプトの配置先
Claude Code	プロジェクトのルートにある CLAUDE.md
Claude Desktop	Settings → Custom Instructions
その他の MCP クライアント	システムプロンプト／カスタム指示欄

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

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

Claude Desktop

claude_desktop_config.json を編集します。

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

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

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

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

仮想環境にインストールした場合は、Claude Desktop が正しいインタープリターを使うよう、仮想環境の Python のフルパスを指定します。

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

Claude Code

claude mcp add を使用してサーバーを登録します。AIMFP に管理させるプロジェクトフォルダー内からコマンドを実行してください。

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

スコープ	効果	おすすめの用途
--scope project（推奨）	現在のディレクトリに .mcp.json を作成します。git で共有できます。	チームでの利用とプロジェクトごとの制御
--scope local	現在のディレクトリに対応付けて ~/.claude.json に保存されます。個人用です。	個人でのプロジェクトごとの利用
--scope user	開くすべてのプロジェクトで利用できます。	すべてのプロジェクトで AIMFP を使用する開発者

pip install（システム全体）：

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

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

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

python3 のみを指定するとシステムの Python が使用され、パッケージがインストールされていません。MCP サーバーのサブプロセスがインストール済みのパッケージを見つけられるよう、venv のインタープリターへのフルパスを使用してください。

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

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

クイックリファレンス：

インストール方法	Claude Code コマンド
pip install aimfp（システム）	-- python3 -m aimfp
pip install aimfp（venv）	-- /path/to/venv/bin/python3 -m aimfp
手動フォルダー／ソースから	--env PYTHONPATH=/parent/of/aimfp -- python3 -m aimfp

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

Claude Code：すべての AIMFP ツールを事前承認する（任意）

これらのツールの実際の動作： AIMFP は、指定したプロジェクト内でのみ動作します。そのプロジェクトディレクトリの外にあるものを読み取ったり、書き込んだり、アクセスしたりすることはありません。また、プロジェクト内では、AIMFP 自身の状態はすべて単一の .aimfp-project/ フォルダーに保存されます。250 以上あるツールの大半は、ローカルの SQLite データベース .aimfp-project/project.db に対する通常の CRUD 操作（タスク、マイルストーン、モジュール、プロジェクトの状態の追跡）と、同梱されたプロジェクト指示の読み取り専用検索です。ネットワークへの接続、認証情報の使用、より広い範囲のファイルシステムへのアクセスはありません。

Claude Code の設計上、MCP ツールを初めて呼び出すときに、そのツールの承認を求められます。250 以上のツールがあるため、各ツールにつき一度ずつ確認を求められます。煩雑ではありますが、確認の内容は毎回、ローカルデータベースまたは指示への呼び出しを Claude Code が確認するだけです。確認を省略するには、Claude Code の 許可リスト ファイル（.claude/settings.local.json）をプロジェクトに配置します。これは「これらのツール名は事前承認済みです」と Claude Code に伝えるだけの静的な Claude Code 設定ファイルであり、AIMFP がダウンロードしたり実行したりするものではありません。

AI に設定を依頼するだけです：

"Set up AIMFP permissions for Claude Code"

AI は get_claude_permissions ツールを呼び出し、完全かつ最新の許可リストを取得します（ツールレジストリからリアルタイムで生成されるため、古くなったり、不完全になったりすることはありません）。その後、AI はそのファイルを書き込むか、.claude/settings.local.json がすでにある場合は、その内容にマージします。マージによって AIMFP 以外のすべての権限と、すでに設定されているその他の項目が保持され、AIMFP の項目のみが更新されます。各ツールは Claude Code が使用できる両方の名前（.mcp.json サーバーの場合は mcp__aimfp__*、プラグインの場合は mcp__plugin_aimfp_aimfp__*）で許可リストに登録されるため、どちらのインストール方法でもこのファイルを使用できます。AIMFP 自身がこのファイルを書き込むことはありません（プロジェクト外には一切アクセスしません）。通常のファイル書き込み確認を経て、AI が書き込みます。最初に get_claude_permissions を呼び出す際の確認を承認すれば、残りの確認はすべて不要になります。

2 つの MCP 自動起動キー（enableAllProjectMcpServers と enabledMcpjsonServers）は自動的に含まれるため、プロジェクトに .mcp.json がある場合、AIMFP サーバーは自動的に起動します。

注：この許可リストの事前作成済みファイルは documentation/settings.local.json にも含まれています。直接確認したり、手動でコピーしたりする場合にご利用ください（cp documentation/settings.local.json /path/to/your/project/.claude/）。インストール済みバージョンと常に同期されるため、get_claude_permissions ツールを使う方法をおすすめします。

その他の MCP クライアント

サーバーは stdio トランスポートを使用します。クライアントから python3 -m aimfp（または仮想環境の Python のフルパス）を指定してください。手動でインストールする場合は、PYTHONPATH に aimfp/ フォルダーの親ディレクトリが含まれていることを確認してください。API キーや認証は必要ありません。

仕組み

サーバーは Model Context Protocol を使用し、stdio 経由で通信します。aimfp_core.db（指示データベース）は、環境変数を必要とせず、サーバー自身のインストール先を基準に解決されます。

接続後、AI はシステムプロンプトの指示に従って、やり取りのたびに aimfp_run() を呼び出します。プロジェクトの状態は作業ディレクトリの .aimfp-project/ に保存され、プロジェクトの初期化時に自動的に作成されます。

プロジェクトの初期化

AI アシスタントに次のように伝えてください：

"Initialize AIMFP for my project"

AI は aimfp_init を呼び出し、プロジェクトのルートに .aimfp-project/ フォルダーを作成します。このフォルダーには、プロジェクトの状態追跡用データベース、ユーザー設定用データベース、ProjectBlueprint ドキュメントが格納されます。これらのファイルを操作する必要はありません。MCP サーバーが自動的に管理します。

---

指示システム

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

FP ベースライン（常時有効）：

• AI がコードを書く際に自然に従う、中核となる関数型プログラミングのルール
• 純粋関数、不変性、OOP を使用しないこと、明示的なエラーハンドリング
• 交渉の余地なし — すべてのコードが FP に準拠する必要があります

FP ディレクティブ（リファレンスドキュメント）：

• 複雑なシナリオやエッジケースに関する詳細なガイダンス
• AI が実装に確信を持てない場合にのみ参照します
• カテゴリ：純粋性、合成、エラーハンドリング、OOP の排除、最適化
• 例：fp_purity、fp_monadic_composition、fp_result_types、fp_wrapper_generation

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

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

レベル	ディレクティブ	目的
レベル 0	aimfp_run	ゲートウェイオーケストレーション（すべてのインタラクション）
レベル 1	aimfp_status、aimfp_init、project_task_decomposition	ステータス、初期化、ハイレベルな調整
レベル 2	project_file_write、project_update_db、project_task_update	運用上の実行
レベル 3	project_compliance_check、project_evolution	状態管理
レベル 4	project_completion_check、project_archive	検証と完了

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

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

ディレクティブ	目的
user_preferences_sync	ディレクティブの実行前に設定を読み込みます
user_preferences_update	ユーザーのリクエストをディレクティブに対応付け、設定を更新します
user_preferences_learn	ユーザーの修正から学習します（確認が必要）
user_preferences_export	バックアップや共有のために設定を JSON にエクスポートします
user_preferences_import	JSON ファイルから設定をインポートします
project_notes_log	ディレクティブのコンテキストとともに project.db への記録を処理します
tracking_toggle	トークンコストの警告とともに、トラッキング機能を有効／無効にします

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

ユースケース 2 専用：AIMFP がコードベースを生成・管理する自動化プロジェクト：

ディレクティブ	目的
user_directive_parse	YAML/JSON/TXT のディレクティブファイルを解析し、構造化されたディレクティブを抽出します
user_directive_validate	対話形式の Q&A を通じてディレクティブを検証し、曖昧な点を解消します
user_directive_implement	src/ に FP 準拠の実装コードを生成します
user_directive_approve	有効化前のユーザーテストと承認のワークフロー
user_directive_activate	ディレクティブを有効としてマークします（デプロイはしません。デプロイは実行ランナーが行います）
user_directive_monitor	事後に健全性、統計、エラーを確認します（読み取り専用）
user_directive_update	ディレクティブのソースファイルの変更に対応します（再解析、再検証）
user_directive_deactivate	ディレクティブを一時停止としてマークします（実行中のプロセスは停止しません）
user_directive_status	すべてのユーザー定義ディレクティブの包括的なステータスを報告します

ユースケース（自動化プロジェクト）：

• ホームオートメーション：「午後 5 時にリビングの照明を消す」、「コンロが 20 分以上ついていたら消す」
• クラウドインフラストラクチャ：「CPU が 80% を超えたら EC2 をスケールする」、「毎晩午前 1 時に RDS をバックアップする」
• カスタムワークフロー：「毎週月曜日にレポートを生成する」、「アップロードされたファイルを自動的に処理する」

主要なアーキテクチャ：

• ユーザーがディレクティブ定義（YAML/JSON/TXT）を記述します
• AIMFP が自動化のコードベース全体（src/、tests/ など）を生成します
• AIMFP は、タスク、ファイル、関数など、生成されたコードを通常のソフトウェアプロジェクトと同様に管理します
• AIMFP はディレクティブを実行せず、実行ランナーも監視しません。生成されたコードがタイマーと処理を担い、AIMFP は aimfp.hooks ライブラリ API を通じて「何が実行予定か」に回答し、「何が起きたか」を記録します
• プロセスを調査しなくても、停止した実行ランナーを検出できます。実行ランナーは次回の実行予定時刻を宣言し、その期限を過ぎても応答がないことが停止の証拠になります
• Project.db は生成されたコードを追跡し、user_directives.db はディレクティブの状態を追跡します

主な機能：

• YAML、JSON、またはプレーンテキストでディレクティブを記述できます
• AI が対話形式の Q&A を通じて検証します
• AI が src/ に FP 準拠の Python モジュール一式を生成します
• AI が生成されたコードのテストを作成します
• 実行は独自のスケジューラーが制御し、AIMFP のフックライブラリを通じて記録されます
• AIMFP がファイルベースのログ（30 日分の実行ログ、90 日分のエラーログ）を書き込み、すべての自動化プロジェクトの記録を同じ形式に保ちます
• セッション開始時に、期限超過、スキップ中、劣化、未実行、エラー状態を報告します
• ユーザーの確認を伴う依存関係管理

ディレクティブ定義の例：

# directives/home_automation.yaml (user creates this in their project)
directives:
  - name: turn_off_lights_5pm
    trigger:
      type: time
      time: "17:00"
      timezone: America/New_York
    action:
      type: api_call
      api: homeassistant
      endpoint: /services/light/turn_off
      params:
        entity_id: group.living_room_lights

ユーザーから AI への指示：「directives/home_automation.yaml のディレクティブファイルを解析してください」

AI が生成するコード（src/lights_controller.py 内）：

# Auto-generated from home_automation.yaml
from typing import Result
from homeassistant_client import HomeAssistant

def turn_off_living_room_lights(ha_client: HomeAssistant) -> Result[None, str]:
    """Turn off all lights in living room group."""
    # FP-compliant implementation
    ...

ワークフローの全説明については、src/aimfp/reference/directives/ にあるディレクティブの MD ファイルを参照してください。

Git 統合

複数ユーザー・複数 AI による開発を支える、FP 対応の Git コラボレーションです。

ディレクティブ	目的
git_init	バージョン管理のために Git リポジトリを初期化または統合します
git_detect_external_changes	AIMFP セッション外で行われたコード変更を検出します
git_create_branch	ユーザー／AI の作業ブランチ（aimfp-{user}-{number}）を作成します
git_detect_conflicts	マージ前に FP 対応の競合分析を行います
git_merge_branch	AI による競合解決を利用してブランチをマージします
git_sync_state	Git ハッシュを project.db と同期し、外部変更を検出します

主な機能：

• 複数ユーザーのコラボレーション：複数の開発者と AI インスタンスが同時に作業できます
• FP 対応の競合解決：純粋性レベル、依存関係、テスト結果を使って競合を自動解決します
• ブランチの命名：aimfp-alice-001、aimfp-bob-002、aimfp-ai-claude-001
• 自動解決：信頼度の高い競合（>0.8）は、FP の純粋性ルールを使って自動的に解決されます
• 外部変更の検出：Git HEAD と保存済みハッシュを比較し、AIMFP 外で行われた変更を検出します
• シンプルなスキーマ：独立した git_state テーブルは不要です。Git コマンドは十分高速です（約1ms）

OOP + Git より AIMFP + Git が優れている理由：

OOP のマージに関する問題	AIMFP FP の解決策
クラス階層が競合する	✅ クラスなし → 階層の競合なし
隠れた状態変更	✅ 純粋関数 → 入出力が明示的
あらゆる場所で副作用が発生する	✅ 副作用を分離 → 競合を簡単に特定
両方のバージョンをテストしにくい	✅ 純粋関数 → テストと比較が容易

競合解決の例：

Alice and Bob both modify calculate_total():

Alice's version:
- Purity: ✅ Pure function
- Tests: 10/10 passing

Bob's version:
- Purity: ✅ Pure function
- Tests: 12/12 passing (includes edge cases)

AI Recommendation: Keep Bob's version (confidence: 85%)
Reason: More comprehensive tests, still pure

複数ユーザーのコラボレーションワークフローの全容については、src/aimfp/reference/directives/ の Git ディレクティブの MD ファイルを参照してください。

---

プロジェクトのライフサイクル

graph TD
    A[aimfp_init] --> B[project_discovery]
    B --> C[project_progression]
    C --> D[project_file_write]
    D --> E[project_update_db]
    E --> F{All Items Done?}
    F -->|No| D
    F -->|Yes| G[project_task_complete]
    G --> H{All Tasks Done?}
    H -->|No| C
    H -->|Yes| I[project_milestone_complete]
    I --> J{All Milestones Done?}
    J -->|No| C
    J -->|Yes| K[project_completion_check]
    K --> L[project_archive]

---

ワークフローの例

プロジェクトの作成

User: "Help me build a matrix calculator"

AI → aimfp_run(is_new_session=true)
    → Receives: session bundle (directive names, status, settings, supportive context)
    → Checks project state: .aimfp-project/ missing → not initialized
    → Calls aimfp_init helper (Phase 1: mechanical setup)
        → Creates .aimfp-project/ directory
        → Creates project.db, user_preferences.db
        → Copies ProjectBlueprint template
    → Enters Phase 2 (intelligent population)
        → Detects language, build tool, source directory
        → Discusses with user: project name, purpose, goals
        → Updates infrastructure table and blueprint
    → Routes to project_discovery
        → Collaborates with user on themes, flows, completion path, milestones

AI: ✅ Project initialized: MatrixCalculator
    Next: Let's define the project shape — themes, completion path, and first milestones.

関数の作成

User: "Write multiply_matrices function"

AI → aimfp_run() (continuation — lightweight guidance)
    → Evaluates: coding task + project tracking needed
    → Has directives cached from session bundle
    → Writes FP-compliant function naturally (pure, immutable, no OOP)
    → Follows project_file_write directive workflow:
        → Reserves file and function IDs in project.db
        → Writes src/matrix.py with embedded IDs
        → Finalizes file and function entries
        → Updates project.db:
           • files table (new entry)
           • functions table (multiply_matrices)
           • interactions table (dependencies)

AI: ✅ Function written: multiply_matrices
    File: src/matrix.py:15
    DB Updated: ✓ files, functions, interactions
    Dependencies: validate_dimensions

準拠状況の確認

User: "Check project compliance"

AI → aimfp_run() (continuation — lightweight guidance)
    → project_compliance_check directive (opt-in tracking feature)
    → Queries all functions from project.db
    → Reviews each function against FP baseline
    → Generates analytics report

AI: 📊 Compliance Report:
    Total functions: 12
    Compliant: 10
    Violations: 2
      - calculate_discount (uses global config)
      - process_order (hidden mutation)

AI の動作のカスタマイズ

User: "Always add docstrings to functions"

AI → aimfp_run() (continuation — lightweight guidance)
    → user_preferences_update directive
        → Calls find_directive_by_intent helper
        → Searches directives by name/description/keywords
        → Finds match: project_file_write
        → Confirms with user: "Apply to file writing?"
        → Updates user_preferences.db

AI: ✅ Preference saved: project_file_write
    Key: always_add_docstrings
    Value: true

    Next file write will include docstrings automatically.

AI が修正から学習

User: "Actually, use guard clauses instead of nested if statements"

AI → user_preferences_learn directive (detects correction)
    → Logs interaction to ai_interaction_log
    → Infers preference: prefer_guard_clauses = true
    → Prompts user: "Should I remember this preference?"

User: "Yes"

AI: ✅ Preference learned: project_file_write
    Key: prefer_guard_clauses
    Value: true

    I'll use guard clauses in future functions.

---

ドキュメント

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

すべてのディレクティブのドキュメントは、パッケージに同梱されています。src/aimfp/reference/directives/ — 131 個の MD ファイルで、すべてのディレクティブを網羅しています。各ファイルには、目的、適用するタイミング、完全なワークフロー（トランク → ブランチ）、準拠／非準拠の例、エッジケース、関連ディレクティブ、使用するヘルパー関数、データベース操作が記載されています。

データベーススキーマ

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

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

---

開発

開発ディレクトリ（dev/）

dev/ ディレクトリには、ディレクティブとヘルパー関数の定義に関する信頼できる唯一の情報源が含まれています。これらの JSON ファイルは、リリース前に aimfp_core.db にインポートされる正式な定義です。

dev/
├── directives-json/              # Directive definitions (source of truth)
│   ├── directives-fp-core.json   # Core FP directives
│   ├── directives-fp-aux.json    # Auxiliary FP directives
│   ├── directives-project.json   # Project lifecycle directives
│   ├── directives-user-pref.json # User preference directives
│   ├── directives-user-system.json # User automation directives
│   ├── directives-git.json       # Git collaboration directives
│   ├── directive_flow_fp.json    # FP directive flow transitions
│   ├── directive_flow_project.json # Project directive flow transitions
│   └── directive_flow_user_preferences.json # User pref flow transitions
├── helpers-json/                 # Helper function definitions (source of truth)
│   ├── helpers-core.json         # Core/directive helpers
│   ├── helpers-orchestrators.json # Entry point and status helpers
│   ├── helpers-project-*.json    # Project management helpers (9 numbered files)
│   ├── helpers-project-modules.json    # Module helpers
│   ├── helpers-project-task-files.json # Task-file link helpers
│   ├── helpers-catalog.json      # Existing-codebase adoption helpers
│   ├── helpers-changeset.json    # Semantic changeset merge helpers
│   ├── helpers-backup.json       # Backup helpers
│   ├── helpers-notices.json      # One-time release notice helpers
│   ├── helpers-settings.json     # User preference helpers
│   ├── helpers-user-custom.json  # User directive helpers
│   ├── helpers-git.json          # Git operation helpers
│   └── helpers-index.json        # Shared/global helpers
├── notices-json/notices.json     # One-time release notices (synced into aimfp_core.db)
├── sync-directives.py            # Imports JSON → aimfp_core.db
├── bump-version.py               # Syncs the package version across the files below
└── logs/                         # Development logs

開発ワークフロー：dev/ 内の JSON ファイルを変更 → src/aimfp/database/aimfp_core.db を削除し、sync-directives.py を実行して再構築 → テスト → リリース。エンドユーザーが使用するのは、事前にデータが格納された aimfp_core.db のみで、JSON ファイルを直接操作することはありません。

バージョンの記載箇所

バージョンを更新する際は、次の4箇所をすべて同期させる必要があります（python3 dev/bump-version.py で実行できます）。

ファイル	変数	目的
pyproject.toml	version = "X.Y.Z"	パッケージのバージョン（PyPI、pip install）
src/aimfp/__init__.py	__version__ = "X.Y.Z"	実行時のバージョン（import aimfp; aimfp.__version__）
src/aimfp/mcp_server/server.py	SERVER_VERSION = "X.Y.Z"	MCP の initialize ハンドシェイク応答（serverInfo.version）
.claude-plugin/plugin.json	"version": "X.Y.Z"	Claude Code プラグインのバージョン

---

設計思想

不変のルールと進化するプロジェクト

• aimfp_core.db はルールブックです（読み取り専用、グローバル、バージョン管理対象）。
• project.db はワークスペースです（読み書き可能、プロジェクトごと、実行時の状態を保持）。
• user_preferences.db はカスタマイズレイヤーです（読み書き可能、プロジェクトごと、AI の振る舞いを設定）。
• ディレクティブが境界を定め、その範囲内で AI は自由に動作します。

データベース駆動のコンテキスト

従来の AI アシスタントには永続的なメモリがありません。AIMFP はこの課題を解決します。

-- AI remembers everything across sessions via helper tools
AI calls: get_project_status("detailed")
→ Returns: project metadata, active milestone, current task, recent notes, tracked files and functions

-- No source code reparsing required. Instant context retrieval.

有限性を前提とした設計

すべての AIMFP プロジェクトには完了までの道筋があります。

Setup → Core Development → Testing → Documentation → Finalization

project_completion_check に合格すると、プロジェクトは完了です。機能が延々と追加されることはありません。

---

機能

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

トークンのオーバーヘッド

AIMFP のプロジェクト管理機能は、セッションごとにトークンのオーバーヘッドを追加します。データベース操作（ファイルの追跡、タスクの更新、マイルストーンの管理）では、コードの記述自体に加えてトークンを消費します。この負担を最小限に抑えるため、継続呼び出しは軽量（約 2k トークン）にし、バッチヘルパーで往復回数を減らし、すべての任意のトラッキングをデフォルトで無効にしています。

プロジェクトの規模が大きくなるほど、その効果が発揮されます。AIMFP を使わない場合、新しいセッションのたびに AI がディレクトリを再スキャンし、ソースファイルを読み直し、コンテキストを一から組み立てる必要があります。コードベースが大きくなるほど、そのコストも増大します。AIMFP を使えば、データベースから構造化されたコンテキストを即座に取得できます。AI は、どのファイルが存在し、そこにどの関数が含まれ、作業がどこで中断し、次に何をすべきかを正確に把握します。少数のファイルを超えるプロジェクトでは、初期のトラッキングコストは、再発見作業をなくすことで何倍にもなって回収できます。

---

使用例

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

ユーザープロンプト：「電卓の作成を手伝ってください」

ツール呼び出し：

1. aimfp_run(is_new_session=true)
   → Returns: session bundle (directive names, settings, project status, supportive context)
   → Status shows: .aimfp-project/ missing — not initialized

2. aimfp_init(project_root="/home/user/calculator")
   → Returns: { success: true, message: "Project initialized" }

動作：

• AI がプロジェクトが存在しないことを検出し、aimfp_init ヘルパーを自動的に呼び出します
• project.db、user_preferences.db、ProjectBlueprint.md を含む .aimfp-project/ ディレクトリを作成します
• プロジェクトのメタデータ（名前、ルートパス、インフラストラクチャ）を登録します
• デフォルトのユーザー設定とバックアップ構成を挿入します
• AI はフェーズ 2 に進み、プロジェクトの方向性（インフラストラクチャ、目的、目標）についてユーザーと話し合います
• 共同で計画を立てるため、project_discovery にルーティングします（テーマ、フロー、完了までの道筋、マイルストーン）

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

ユーザープロンプト：「multiply_matrices 関数を作成してください」

ツール呼び出し：

1. aimfp_run(is_new_session=false)
   → Returns: lightweight guidance

2. reserve_file(name="matrix_operations", path="src/matrix_operations.py", language="Python")
   → Returns: { success: true, id: 42 }

3. reserve_function(name="multiply_matrices", file_id=42, purpose="Multiply two matrices")
   → Returns: { success: true, id: 99 }

   (AI writes FP-compliant code to src/matrix_operations_id_42.py)

4. finalize_file(file_id=42, path="src/matrix_operations_id_42.py", ...)
   → Returns: { success: true }

5. finalize_function(function_id=99, name="multiply_matrices_id_99", file_id=42, purpose="...", parameters=[...], returns={...})
   → Returns: { success: true }

動作：

• 記述前に、ファイルと関数を project.db で予約します（ID は名前に埋め込まれます）
• AI は FP の基本原則に従って純粋関数型コードを記述します（OOP なし、ミューテーションなし、パラメーターを明示）
• 目的、パラメーター、戻り値のメタデータを設定して、ファイルと関数を確定します
• プロジェクトデータベースにコード構造が記録され、今後のセッションで即座に取得できるようになります

例 3：作業の再開／ステータスの確認

ユーザープロンプト：「今どんな状況ですか？」または「作業を続けてください」

ツール呼び出し：

1. aimfp_run(is_new_session=false)
   → Returns: guidance + common starting points

   (AI answers from cached context — no additional DB calls needed
    unless context is stale, in which case:)

2. aimfp_status(type="detailed")
   → Returns: project metadata, active milestone, current task, recent notes, warnings

動作：

• AI が現在のマイルストーン、進行中のタスク、次のステップを提示します
• project_continue_on_start=true の場合、AI は次のタスクに自動的に取り組みます
• ソースコードを再解析する必要はありません。すべて project.db にインデックス化されています

---

プライバシーポリシー

AIMFP はお使いのローカルマシン上で完全に動作します。データがコンピューターの外部に送信されることは一切ありません。

• ネットワークリクエストなし：MCP サーバーはネットワーク呼び出しを一切行いません。すべての操作は、ローカルの SQLite データベースの読み書きとファイルシステム操作です。
• テレメトリなし：利用状況の分析データ、クラッシュレポート、診断データを収集または送信することはありません。
• サードパーティサービスなし：AIMFP が外部 API、クラウドサービス、リモートサーバーに接続することはありません。
• ローカルデータのみ：プロジェクトデータ（データベース、設定、ディレクティブ）はすべて、プロジェクトの .aimfp-project/ ディレクトリに保存されます。すべてのデータはお客様自身が所有し、管理できます。
• Claude のメモリへのアクセスなし：AIMFP が Claude の会話履歴、メモリ、その他のクライアント側データにアクセスしたり、読み取ったりすることはありません。

データの取り扱いについてご質問がある場合は、GitHub リポジトリで issue を作成してください。

---

サポート

• 問題の報告：GitHub Issues
• リポジトリ：github.com/aryanduntley/aimfp

---

コントリビュート

AIMFP は AI に最適化されたプログラミングのオープン標準です。コントリビューションを歓迎します。

1. 新しい FP ディレクティブ — 言語固有のパターンや高度なパターン
2. ヘルパー関数 — データベース、ファイル、Git、FP のユーティリティ
3. テンプレート — ADT のボイラープレート、エラー処理パターン
4. ドキュメント — 例、チュートリアル、ケーススタディ

コントリビューション（プルリクエスト、パッチ、その他の素材）を提出することで、そのコントリビューションが PolyForm Noncommercial License 1.0.0 および AIMFP の著作権者が付与する商用ライセンスの下で配布されることに同意したものとみなされます。また、その許諾を行う権利を有していることを確認したものとみなされます。

---

ライセンス

AIMFP は PolyForm Noncommercial License 1.0.0 の下でライセンスされています。全文については LICENSE をご覧ください。

非商用利用は無料です：個人学習、研究、実験、趣味のプロジェクトのほか、慈善団体、教育機関、公的研究機関、政府機関による利用が含まれます。

商用利用には書面による承認が必要です。 営利目的のあらゆる利用が対象となります。これには、企業による利用または企業のための利用、有償の業務やクライアント向け業務での利用、AIMFP またはその派生物の販売や再配布、有料の製品やサービスの一部として提供することが含まれます。商用ライセンスを申請するには、Aryan Duntley（[email protected]）までご連絡ください。

1.66.1 までのバージョンは MIT License の下で公開されており、それらのバージョンのコピーは引き続き MIT License の下にあります。それ以降のすべてのバージョンは、PolyForm Noncommercial License 1.0.0 の下でのみライセンスされています。

---

まとめ

AIMFP は AI を「コード生成ツール」から、構造化され、カスタマイズ可能なプロジェクトの協働者へと変えます。

以下を組み合わせています。

• 純粋関数型プログラミングによる、決定論的で合成可能なコード
• 不変のルール、実行時の状態、ユーザーによるカスタマイズ、任意の自動化を実現する4 データベースアーキテクチャ
• 一貫性のある自動準拠を実現するディレクティブベースのワークフロー
• コーディングスタイルに適応する AI を実現するユーザー設定の学習
• 目標指向の開発を実現する有限の完了パス
• オプトインのトラッキング機能を備えたコストを意識した設計

その結果、セッションやチームをまたぎ、異なる AI アシスタント間でも、AI が保守するコードベースを予測可能、追跡可能、カスタマイズ可能、保守可能にします。

---

AI ネイティブな開発時代のために構築されました。