【要約】Notion を canonical にして AI 開発パイプラインを組んだら踏み抜いた 5 つの落とし穴 [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
- ・同期ラグにより、AIが古い前提でPRを作成する。
- ・人間による手編集とAIの書き戻しが衝突し、データが消失する。
- ・Webhookでは新規リソースを捕捉できず、APIレート制限に抵触する。
- ・Notionのコメント構造が複雑で、DBとの完全な同期が困難。
- ・AIが意図しない列を書き換える境界の曖昧さによる事故。
// Approach
1.
notion_synced_at カラムを導入。updated_at と分離し、同期方向を判定。2.衝突検知ロジックを実装。
force=true を人間のみに許可し、自動同期での上書きを禁止。3.差分カーソル方式のポーリングを採用。Celeryによるタスク制御、±60秒のジッター、100件単位のバッチ処理を併用。
4.コメントをフラットに保持。メタデータを本文に埋め込む非対称な設計を採用。
5.
NotionDatabaseConfig を導入。AIの書き込み範囲を列単位で厳格に制限。// Result
- ・同期状態の可視化により、データ消失リスクを低減。
- ・Celeryとジッターの併用で、APIレート制限を安定的に回避。
- ・AIによる意図しないプロパティ更新を物理的に遮断。
- ・Notionの仕様に左右されない、堅牢な同期基盤を構築。
Senior Engineer Insight
> Notionを正本とする設計は、ビジネスサイドとの親和性が高い。しかし、DBは単なる「コピー」ではなく「同期状態の管理層」として再定義すべきだ。特にAIを組み込む場合、プロンプトによる制御は限界がある。
NotionDatabaseConfig のように、コードレベルで書き込み境界を物理的に閉じる設計が、大規模運用におけるデータ整合性を担保する鍵となる。