@kekkai/blueprintArchitecture as Code
將前端架構轉化為 ESLint 規則與 AI Agent 守則
Skip to content
為什麼需要它
放手讓 AI 寫程式，你會悄悄付出哪些代價？Blueprint 又如何逐一解決。
程式分層
AI 交出一個能正常運作的功能，卻把新檔案隨手放在方便的位置。幾個 session 之後，每個檔案都偏離了它原本該待的地方。
→ blueprint 定義每一層程式的歸屬，跨越邊界就交給 lint 擋下
看解法 →單一職責
「先能動就好。」於是 AI 不斷把更多職責塞進同一個檔案，最後一個模組做了五件事，卻沒有一件真正屬於它。
→ blueprint 把單一職責寫進守則，並由 lint 守住最基本的機械底線
看解法 →檔案大小
每一次 AI 修改，都讓檔案再膨脹一點。三個月後，一個模組已經長到 6,000 行，而之後每個 agent 只是想改一個 function，都得先載入整個檔案。
→ blueprint 在檔案開始消耗大量 token 前，先替它設下上限
看解法 →可讀性
功能通過了。但 AI 最佳化的是「完成」，不是「讓下一個人容易理解」。而下一個閱讀的人，很可能就是另一個 AI agent。
→ blueprint 讓每個 session 都依循同一套可讀性標準
看解法 →一致性
每一次 session，AI 都重新推導一次你的架構，而且每次推導出的結果都不太一樣。
→ blueprint 給每個 session 同一份寫下來的架構守則
看解法 →導入
把它套到一個三年的舊專案，你大概會看到四千個錯誤。於是團隊第一天就把它關掉。
→ blueprint 鎖住今天的技術債，只阻擋新增的問題
看解法 →一份設定，全面落地
blueprint.config.mjs
eslint.config.mjs
docs/architecture-handbook.md
CLAUDE.md · AGENTS.md · …
inspect · deps · rules
改設定、重新生成，所有產出結果一起變更 —— 它們不會漂移，因為全部是同一份來源轉譯出來的。詳細內容見 init 產出結果。
快速上手
既有專案導入，兩種方式。
你幾乎不用貼什麼 —— init --authoring 會寫出 playbook，其餘的（跑到底、什麼叫做完）它自己交代給 agent。
全自動
丟一段 prompt 給你的 agent —— 它自己從頭跑到尾。
貼給你的 agent
請執行 npx @kekkai/blueprint init --authoring 協助導入 @kekkai/blueprint
每個驗收步驟在防什麼、完整流程，見 AI 協助導入。
工程理念
Blueprint 的工程理念涵蓋以下面向 —— 全都會編進你的 repo，成為 lint 規則與 agent 守則：
01分層架構程式放哪、誰可以 import 誰。
02元件設計一個單元怎麼切、多大。
03核心信念單一事實來源、成本、死碼⋯⋯
04工作紀律執行期負載、死碼、重構手法。
Blueprint 不談 framework 的最佳實踐 —— 依專案的技術選型，挑對應的搭配資源：
- React & Next.js —— vercel-labs/agent-skills：
Vercel Engineering 的最佳實務 skill 包，與 blueprint 守則並用，
讓 Agent 同時拿到你的結構規範與框架慣用寫法。 - Vue —— vuejs/docs：
官方文件原始碼，提供給 Agent 作為 API 權威依據，搭配 Vue preset。
Blueprint 管「程式碼放哪」，框架資源管「怎麼寫得道地」 —— 兩者一起，縮短「能跑」跟「寫得對」的距離。完整理念見 工程理念。