freee 会計・人事労務データを「事実 (Facts) と規則 (Rules) の集合」として取り込み、クエリ・監査・インタラクティブなグラフで分析するスキル。本番 freee データへの書き込みは発生せず (オンメモリ独立環境)、多様な入り口 (API 同期 / 自由 transact / LLM 試作) を同じグラフモデルに吸収する。
DataLog は MCP サーバー起動時に空の状態で立ち上がる。freee API データは 明示的に datalog_sync_* を呼ばない限り 1 件も投入されない (自動同期は無い)。クエリや監査を走らせる前に、対象ドメインに応じて以下を順に実行すること。
freee_auth_status で OAuth トークンが有効か確認 (期限切れなら freee_authenticate)freee_set_current_company で対象事業所を選択datalog_reset でクリーンな環境を確保 (再 sync 時は必須)
datalog_reset を呼ばない。エンジンは共有なので他利用者が投入済の datom / 検証データ (共有 30 件等) を破壊する。共有環境では reset せず、対象データを追加 sync するだけで足りる。手元の専有 sandbox でのみ reset 可。判断に迷うなら reset を省略する (= 非破壊側に倒す)datalog_visualize で取り込み結果を確認注意点:
datalog_sync_* は 差分同期ではなく全件取得。再実行で重複は発生しないが、削除されたエンティティを反映するには datalog_reset を挟む必要があるdatalog_sync_deals / datalog_sync_account_items は内部で概念ノード (取引/明細/勘定科目 等) を最初の呼び出しでプリセットする。datalog_sync_partners は単独では概念ノードを作らないので、deals か account_items の sync を先に走らせること (順序逆だと "Nothing found for entity id ('node/name' '取引先')" でエラー)datalog_sync_work_record_summaries は datalog_sync_employees の後でのみ動作 (emp ノードが無いと早期 return)datalog_query / datalog_audit_run_all を sync 前に走らせると空結果が返るだけで失敗扱いにはならない。「データが無い」と「クエリが間違っている」の区別がつきにくいので、必ず初期設定 (上記 1-4) を済ませてから検証する| ツール | 役割 |
|---|---|
datalog_schema |
現在のスキーマ情報 (固定 + 登録済み + 動的統計 + 推奨クエリ) を一括で返す |
datalog_query |
任意の datalog クエリを実行 |
datalog_reset |
DataLog 環境を初期化 |
datalog_transact |
任意 datom を投入 (persist=true で durable 永続化) |
datalog_retract |
durable に永続化した datom のうち指定したものだけを撤回 (= 検証フィクスチャの後始末。 reset 全消しと違い対象限定) |
datalog_sync_* |
freee API からデータ同期 (account_items / partners / tax_codes / deals / user_matchers / employees / work_record_summaries) |
datalog_visualize |
HTML 可視化 (自動更新) |
datalog_audit_list / datalog_audit_get / datalog_audit_create / datalog_audit_update / datalog_audit_delete / datalog_audit_run_all |
AuditQuery (監査クエリ) CRUD + 全件走行 (現行の正典モデル)。query は [:find ?x :where ...] selector。GUI と同じ store に書くのはこちら |
datalog_predicate_list / datalog_predicate_get / datalog_predicate_create / datalog_predicate_update / datalog_predicate_delete |
DomainPredicate (IDB / 派生述語) CRUD (現行の正典モデル)。query が rule body。is_detail_of 等のドメイン述語をここで作る |
datalog_testcase_list / datalog_testcase_get / datalog_testcase_create / datalog_testcase_update / datalog_testcase_delete / datalog_testcase_run |
TestCase (header: title / dataSource / kind / statuteDescription) CRUD + 配下 row 一括走行。parentKind=audit_query | domain_predicate + parentId で親に紐付く |
datalog_testrow_list / datalog_testrow_get / datalog_testrow_create / datalog_testrow_update / datalog_testrow_delete |
TestRecordV2 row (nodeKey / expectedKind / businessExpectation / freeeReqBody) CRUD。TestCase 配下の test データ 1 行 |
datalog_server_info |
サーバ build 情報 (commit / deploy 時刻) を返す。版数文字列が再デプロイ跨ぎで据え置きでも、どのビルドを叩いているか判別できる (= FB 切り分け用) |
test の設計・作成は TestCase + testrow の親子モデル (
datalog_testcase_*+datalog_testrow_*、上表) を使う。TestCase 1 件 = header (title / dataSource / kind / statuteDescription) で、その配下に複数 testrow (= nodeKey / expectedKind / businessExpectation / freeeReqBody)。走行はdatalog_testcase_run。観点設計は audit-test-design-skill / freee-api-test-record-skill を参照。
freee_set_current_company → datalog_reset → datalog_sync_account_items
→ datalog_sync_partners → datalog_sync_tax_codes → datalog_sync_deals
→ datalog_sync_user_matchers (任意: 自動仕訳ロジック監査用)
→ datalog_visualize
datalog_sync_user_matchers は freee の自動登録ルール (UserMatcher) を取り込む。明細の自動仕訳ロジック (条件 / 適用 act / 適用先 account_item) を DataLog で照合できるようになり、「ルール適用結果と実 account_item の乖離」「無効化されたまま放置されたルール」等の監査が可能。
freee_set_current_company → datalog_sync_employees
→ datalog_sync_work_record_summaries year=YYYY month=M → datalog_visualize
datalog_transact {...} → datalog_query → datalog_visualize
datalog_schema (初回のみで全体像取得)
→ 興味のある概念名を特定
→ datalog_query (返された recommendedQueries を参考に)
→ 必要なら datalog_audit_create で監査化 / datalog_predicate_create でドメイン述語化
:in $ % 経路差、Pre-flightdeal_/detail_/partner_/emp_/workrec_/... 命名規則skill-only クライアント (= この skill を MCP 経由でしか読めない素の AI) は、上記 references を
datalog_skill_listで一覧しdatalog_skill_get（例references/query-syntax.md）で本文取得できる。
datalog_schema → 推奨クエリ → datalog_query の手順datalog-store/<base>.local.<breaking>.json) は絶対に手編集しない
datalog_audit_create / datalog_audit_update / datalog_audit_delete、ドメイン述語は datalog_predicate_create / datalog_predicate_update / datalog_predicate_delete (現行の正典モデル)datalog-store/<base>.<breaking>.json) のみ手編集可
[?e "is_a" ?c] [?c "node/name" "..."] のような型検査の繰り返しは
対応する述語 (例 is_detail_of, is_partner_of, is_payment_instance_of) に畳む:where に :in $ % を書けば runner がドメイン述語集合を自動注入するdatalog_predicate_create / datalog_audit_create) を作ったら、datalog_testcase_create で TestCase を紐付け、datalog_testrow_create で期待付き test 行を足し、datalog_testcase_run で passing を確認scope='user': test 0 件可scope='organization' (= org-admin caller のみ作成可): test 1 件以上必須scope='common' (= app-admin caller のみ作成可): test 1 件以上必須expectedKind (truePositive / trueNegative / outOfScope) と businessExpectation (業務期待値 ordinal) を持つ。user の石入れ (確定 2 値) は GUI の test-cases-v2 画面で行う (= 共有範囲 writeGroups で編集可否)。statuteDescription 必須)
userDescription: ドメインユーザー向け平易日本語 (集合論レベル / プログラミング用語禁止)engineerDescription: エンジニア / AI 向け技術疑似コード (旧 pseudocode の役割)statuteDescription: 税理士 / 会計士 向け 法文風 (= 条文風) Markdown 詳細。
audit query (= datalog_audit_create / datalog_audit_update) では 必ず 埋める (= 詳細書式は statute-description)。
ドメイン述語では 不要。 既存 query を update する 際に 空のまま 上書き しない (= 既存値を 必ず 引き継ぐか、 改訂版を 出す)。active (本番) / not_active (停止) / updating (試作中、create 既定) / outdate (breaking ver up 後の未対応)not_active=0 / outdate=10 / deprecated=20 / updating=30 / active=40)test の 走行結果 + 設計段階 を 1 enum (int ordinal、 末端 = 健全) で 表す。 datalog_testcase_run が persist し、byRunStatus 集計でも使う:
| ordinal | name | label | 意味 |
|---|---|---|---|
0 |
untested |
未走行 | まだ 走らせて いない |
5 |
query_pending |
クエリ未完成 | 親 audit query が 未完成 (= 走行 不可) |
7 |
test_design_pending |
テスト設計中 | header / 期待 だけ で datoms 未充足 (= 走行 不可) |
10 |
error |
走行エラー | 走行 中 に 例外 |
20 |
failing |
失敗 | 走行 結果 が 期待 と 不一致 |
30 |
passing |
成功 | unit 走行 OK (= datom_only の terminal green) |
40 |
e2e_passing |
E2E 成功 | freee 実投入 + 実走行 まで 通った 最上位 |
runStatus ≠ rule の status (= 別 enum)。 runStatus は test 行 の 走行/段階、 status は rule/query の 稼働状況。
*_delete / datalog_reset) は user の明示指示が有る時だけ。fbtest* を AI が「片付け」と称して勝手 delete し、 user の GUI 確認を壊した。 再発防止としてこの鉄則を置く。datalog-store/ 配下の common / local 両方にバージョンタグ (<major>.<minor>、ゼロ詰め無し) が埋め込まれる:
common: <base>.<breaking>.json 例: query.0.0.json
local : <base>.local.<breaking>.json 例: query.0.0.local.json
<breaking> は package.json.version の major.minor 部分に追従する。
0.0.1 → 0.0.2): 後方互換、データファイル変更不要0.0.x → 0.1.0): breaking、common と local 両方を新タグへ書き直す必要がある (datalog-migration-skill を参照)旧 breaking 版の local ファイルは並列に残せる (= 現行版でないものは識別可能)。書き直し完了後に git rm で削除可。MCP CRUD ツールは現行 breaking 版にのみ書き込む。
クエリを書く前に必ず datalog_predicate_list で既存ドメイン述語 (DomainPredicate / IDB) を確認し、活用可能なら畳む。型検査の繰り返し ([?e "is_a" ?c]...) は対応する述語 (例 is_detail_of) に畳み、:find 直後の :in に $ % を必ず含める (忘れると Missing rules var '%' in :in で失敗、空返りではない)。試作は :in $ % 無しのアトミック述語で動作確認 → 安定後に datalog_predicate_create + datalog_audit_create で監査化。
good/bad の EDN 例、:in $ % 経路差 (audit 走行は自動注入 / ad-hoc datalog_query のみ inputs 明示)、Pre-flight チェックリストは idb-first-fewshot を参照。
datalog_resetdatalog_reset fullReset=true (破壊的)/tmp/datalog_graph_latest.html に常時上書きdatalog_reset → sync を再実行datalog_sync_* は freee API 認証前提。事前に freee_auth_status で確認原則: normal user 経路 (= MCP tool 連続呼び出し + 必要に応じた手編集) では reconnect 一切不要。reconnect が要るのは「コード変更で bin を入れ替える」開発作業時のみ。
reconnect 要否マトリクス:
| 変更内容 | reconnect | 理由 |
|---|---|---|
datalog_*_create/update/delete 等の MCP CRUD |
不要 | notifyChanged() → refreshIdbRules() で in-memory cache 自動更新 |
datalog-store/*.json の手編集 |
不要 (local) / 要 (common 反映) | listQueries/listIdbRules は file 毎回再読込。ただし IDB rule edn は CRUD 経由でのみ refresh されるので、手編集後は最初の CRUD or datalog_reset 等で発火する |
bun run build:ui のみ (UI bundle 差分) |
不要 | loadBundle() は visualize 毎回 disk 読込 → 次の datalog_visualize で新 bundle 反映 |
bun run build 全体 (bin 再生成) |
要 | MCP host が新 bin を読み直すため |
| 新 MCP tool 追加 / Zod schema 変更 | 要 | bin 再生成必須 + tool 一覧は connect 時取得 |
機能完了の前に必ず: 想定 user 操作 (例: create → test → list / reset → re-sync → visualize) を vitest で e2e shape のテスト にし、reconnect 無しで pass することを確認する。
audit query (= datalog_audit_create / datalog_audit_update) で 必ず 埋める 3 つ目の description。税理士 / 会計士 が 税法・会計基準 と 同じ 語彙・文体 で 読めるよう、条文風 + 箇条書き の Markdown を持つ (新規作成時は caller 未提供でも userDescription + engineerDescription から draft 生成、update 時は既存値を必ず引き継ぐ)。DomainPredicate (= datalog_predicate_create / datalog_predicate_update) では不要。
書式規約 (記号優先・主語明示・出典は確証時のみ)、3 系統 description の役割分担、few-shot 例 (収支区分矛盾 / 帳簿要件 / 36 協定)、強制ルールは statute-description を参照。