A friend at my church brought an old Mac in a few weeks ago. He wanted to run n8n on it and turn it into our congregation's AI experimentation ground — automating the tedious stuff: rosters, reminders, the small administrative debt every volunteer organization accumulates. Reasonable idea. Then he had to answer the question every home-lab builder eventually hits: how do you let people reach a service running on a machine sitting behind your gateway, without opening that gateway to the entire internet?

He had a Synology NAS already, so he did what a lot of careful people do — he put the NAS's VPN server in front of the Mac and decided nobody talks to n8n unless the VPN tunnel is up. Sound instinct. And it's exactly where I want to start, because the failure mode he was avoiding, and the one he stepped into instead, are both symptoms of the same disease: we've been authenticating devices and networks when we should have been authenticating people.

The Hole You Dig Either Way

The alternative to VPN is remote desktop — RDP or VNC into the Mac directly. It's tempting because it needs zero client setup. Point a browser or a thin client at an address, type a password, done. Which is exactly the problem: "point an address at it" means the address has to be reachable, which means a port has to be open on the gateway, forwarded to a machine inside your private network. Every scanner on the internet finds that port eventually. RDP has one of the worst exposure track records in networking — it's a perennial top vector in ransomware post-mortems precisely because it's a direct, authenticated-at-the-endpoint tunnel into a box that usually has broad filesystem and process access. You're not exposing "a service." You're exposing a full desktop session.

So VPN is the correct instinct. Terminate access at the tunnel, not at the app. But now you've traded one problem for a slower, more annoying one. A VPN needs a client. Someone has to download WireGuard or OpenVPN, import a config file, and — this is the part that kills adoption in a volunteer organization — understand what a config file is. And on the network side, you often still need to open a UDP port on the gateway for the VPN server to be reachable from outside, which means someone has to know what port forwarding is and be trusted to touch the gateway's admin panel to set it up.

None of this is hard for an engineer. It is completely opaque to the person in your church who just wants automated reminders to go out on Tuesdays. And that's the actual constraint: whatever you build has to be operable by people who will never read a networking doc.

Reframing the Problem

Here's the thesis: the friction in both remote desktop and VPN isn't a UX problem you can smooth over with a nicer wizard. It's a modeling problem. Both approaches treat authentication as something that happens to a device at a location — this IP, this port, this machine's private key, configured once, sitting there as a static grant. Change the device, change the network, add a new person, revoke an old one, and you're back into the gateway's admin panel, hand-editing config.

The fix isn't a better VPN client. It's moving the unit of trust from "this device on this network" to "this account, verified continuously, wherever it happens to be." Once identity is the thing being checked — not location, not a static tunnel config — the network topology becomes an implementation detail the system manages for you instead of a thing your users have to reason about.

How Ubiquiti Actually Does This

This is the part I've been close to, because I lead the SSO team at Ubiquiti, and I want to describe it precisely rather than just gesture at "the cloud does it."

Ubiquiti's newest answer to this is UniFi Fabric, a concept the company rolled out only this past year: a set of identities, not the gateway, now governs a set of devices. You bind your consoles into a Fabric, and access to whatever's running behind them becomes a property of who you invite, not a config file you hand out. VPN comes built into that model, not bolted onto it.

Once that's live, granting my friend access to the n8n box isn't "give him the VPN config file." It's assigning a role to a person in Site Manager's People view. The moment a role or permission lands on someone, UniFi automatically sends them an invitation to the UniFi Endpoint app — the identity client, on desktop and mobile — with a 2FA code baked into onboarding. He installs the app, authenticates once, and from that point on the app itself is the credential. No config file changed hands. No port was opened for him personally.

The VPN leg specifically is handled by Teleport, which is where the "no port forwarding" claim actually earns itself. Teleport uses WireGuard, but instead of requiring the gateway to be directly reachable from the internet, the gateway maintains an outbound connection to Ubiquiti's cloud relay. When my friend's device wants in, the connection is brokered through that relay — the gateway never needed an open inbound port, because it never needed to be reachable; it only ever had to reach out. That's the same trick NAT traversal and reverse tunnels have always used, just packaged so nobody has to know the word "NAT traversal" to benefit from it.

Stack those two things and you get what my friend actually wanted: invite a person, they get one-click VPN, the gateway's attack surface never grew, and nobody had to be taught what a port is.

This Isn't New — It's BeyondCorp for Your Garage

I want to be honest about what's genuinely novel here versus what's good packaging. The underlying idea — stop trusting network position, verify identity and device posture on every request — is Zero Trust Network Access, and it's been enterprise doctrine since Google published the BeyondCorp papers describing how they let employees work from any network, coffee shop included, without a traditional VPN, by making every request prove who was making it. "Never trust, always verify," identity as the new perimeter — none of that language is new, and none of it originated at Ubiquiti.

What's actually happening is that a decade of enterprise-grade identity infrastructure — IdP federation, continuous authorization, cloud relay for NAT traversal — is getting compressed into a product a single person can operate for their home network or their church's spare Mac. That compression is the real story of the AI home-lab moment: the people spinning up n8n or a local LLM on hardware in a closet are, without necessarily knowing it, recreating the access-control problem that enterprises spent ten years and considerable headcount solving. They just don't have a security team. The gateway vendor becomes the security team, by default, whether it wants the job or not.

The Security Surface You're Actually Choosing

Here's the part of the argument I'd push back on if I heard someone else make it uncritically: shifting authentication from per-device config to account identity doesn't remove risk, it concentrates it. A leaked WireGuard config compromises one tunnel to one machine. A compromised account, once role-based and federated across WiFi, VPN, and door access, is a much bigger blast radius if it falls into the wrong hands. Centralizing identity is a bet that you can secure the few things that matter — MFA, session policy, anomaly detection on the identity provider — better than you could secure the many things that used to be scattered: a dozen device configs, a dozen static keys, a port-forward rule someone added in 2019 and forgot about.

I think that bet is correct for the overwhelming majority of people, not because account compromise is rare, but because it's a legible risk. You can reason about "is 2FA on, is the session policy sane, has this account done anything unusual." You cannot reason about "which of the forty devices that ever got a VPN config still has it, and is that laptop still in the drawer it was left in." Distributed, invisible trust grants are harder to audit than one well-guarded identity, even though the identity is a scarier single point of failure on paper. Ninety percent of people are safer trusting one strong lock than managing forty forgotten ones — the other ten percent, running real infrastructure at scale, still need the layered device posture and network segmentation that pure identity-centric models compress away. That's a real tradeoff, not a solved problem, and anyone telling you identity-first access has no downside is selling you something.

What This Has to Do With AI Infrastructure

Ubiquiti sells switches, gateways, cameras, WiFi access points. It sells zero AI products. And yet the exact pattern I watched solve my friend's church-automation problem is the pattern every AI home lab and, at a different scale, every AI factory is going to need: a growing population of self-hosted services — n8n instances, local inference servers, agent runners — sitting on private networks, that need to be reachable by specific people without turning the network inside out. Nobody wants to hand-configure a VPN client for every teammate who needs to hit an internal model endpoint, and nobody wants that endpoint exposed to the raw internet either.

The companies that end up mattering to the AI infrastructure stack won't only be the ones selling GPUs and model weights. Some of them will be the ones that already figured out how to make "only the right person, from anywhere, with zero manual network configuration" a one-click default instead of a networking elective. My friend never once thought about IP addresses, VPN clients, or port forwarding to get his automation ground running securely. He thought about who he wanted to invite. That's the interface AI infrastructure needs at every layer above the silicon, and it's a stranger thing than it should be that the company already building it is one nobody associates with AI at all.

MCP was genuinely great at first

When we first wired up mcp-atlassian to Claude Code, it felt like magic. "Create a Jira ticket for this bug." Done. "Update the Confluence page with the new architecture." Done. The MCP server handled authentication, request construction, Atlassian Document Format – all the tedious plumbing that makes the Atlassian API unpleasant to use directly. We had 71 tools at our fingertips and didn't have to think about any of them.

For generic, one-off tasks, this was perfect. The problem started when we wanted things done our way.

We got tired of repeating ourselves

Every time we created a ticket, we had to say: "Use project Cloud-Team. Set the component to Cloud-Core. Prefix the title with [Cloud]. Assign it based on the current sprint rotation." Every time we created a Confluence page, we had to specify the space, the parent page, the heading structure. And half the time the formatting came back wrong anyway -- list items with broken bold text, headings where there shouldn't be headings, descriptions that needed a second pass to fix.

We were spending as much time correcting output and restating preferences as we would have spent doing the work manually. The tool was fast but imprecise, and precision is what you need when every ticket and every page feeds into your team's workflow.

So we built skills on top. A jira-ticket skill that encoded our project defaults, title conventions, component assignments, and custom field handling. A confluence-page skill that knew our space structure and formatting standards. These skills invoked the MCP tools underneath -- jira_create_issue, jira_update_issue, confluence_create_page -- but wrapped them in our team's specific logic.

This worked. For a while.

Then the MCP upgraded and broke everything

The mcp-atlassian package shipped a new version, and our skills broke. Tool names changed. Parameter formats shifted. Behaviors we relied on silently disappeared.

We rewrote our skills to match the new version. And in doing that rewrite, we started noticing things we'd been blissfully ignorant of.

The Jira REST API has multiple versions. Version 2 accepts Markdown-ish text for description fields. Version 3 requires Atlassian Document Format -- a JSON structure with typed nodes, marks, and nested content. The MCP server was converting our Markdown input into ADF internally, and that conversion was where five of our six documented bugs lived: bold text inside list items rendered wrong, underscores triggered false italics, hash characters were parsed as headings, leading spaces vanished, horizontal rules appeared where they shouldn't.

We'd been debugging formatting issues at the wrong layer. The bugs weren't in our skills or in our input -- they were in a Markdown-to-ADF converter hidden inside the MCP server, a converter we couldn't see, couldn't control, and couldn't fix.

The file upload gap and the Docker problem

Two more friction points pushed us further from MCP.

First: mcp-atlassian didn't support file uploads. That sounds minor until you realize it means no image attachments on Confluence pages, no uploaded diagrams, and critically -- no Mermaid diagram macros. Confluence renders Mermaid diagrams through the mermaid-cloud macro, which references an attached image. Without file upload support in the MCP, we had to do these operations manually: upload the file through some other means, get the attachment ID, then construct the page content referencing it. Half the workflow was inside the MCP abstraction and half was outside it, which is worse than having all of it outside.

Second: the Docker overhead. The version of mcp-atlassian we started with only ran in Docker. Each Claude Code session spawned its own container. Run three sessions in a morning -- reviewing a PR, creating tickets, updating docs -- and you'd have three containers alive, each holding a connection to Atlassian. Nobody was cleaning them up reliably. We'd find stale containers days later.

We eventually switched to a version that ran natively via uvx, which eliminated the container sprawl. But it was another migration, another set of configuration changes, another afternoon spent on tooling plumbing instead of actual work.

The accumulating weight of workarounds

By this point we had:

• A skill layer on top of MCP to encode team-specific behavior

• Six documented converter bugs with workarounds baked into our skills

• A mandatory two-step process for issue creation (create without custom fields, then update to add them, because the converter broke when custom fields were in the same call)

• Manual file upload workflows for anything involving attachments

• Memory files documenting MCP quirks so Claude wouldn't repeat mistakes

• A history of one breaking upgrade already absorbed

We were maintaining more infrastructure around the MCP than the MCP was saving us. And we were still hitting formatting bugs on every third Confluence page update.

That's when I read Mario Zechner's "What If You Don't Need MCP?," and it reframed the problem for me.

Zechner's argument is deceptively simple: MCP servers need to cover all bases, which means they ship large numbers of tools with lengthy descriptions, all permanently consuming context. He measured it. Playwright MCP: 21 tools, 13.7k tokens -- 6.8% of Claude's context window, gone before you ask a single question. Chrome DevTools MCP: 26 tools, 18k tokens, 9% of context. Our mcp-atlassian was worse: 71 tools, ~15-20k tokens, loaded into every session regardless of whether that session would ever touch Jira.

But the context cost was only his first point. The deeper problem is composability. MCP outputs route back through the agent's context before they can be persisted or combined with other results. Every API response, every search result, every page content fetch -- it all lands in the context window as intermediate state, crowding out the space you need for actual reasoning. With a curl command, the agent can pipe output to a file, chain it with jq, or redirect it entirely -- the result doesn't have to pass through context at all.

His solution was minimal bash scripts documented in a README. The agent reads the README, understands the tools, calls them directly. His browser toolkit went from thousands of tokens of tool schemas down to 225 tokens of documentation. And the key insight behind the savings: "This efficiency comes from the fact that models know how to write code and use Bash. I'm conserving context space by relying heavily on their existing knowledge." You don't need a tool schema to teach Claude how to make an HTTP request. Claude already knows curl. What it needs is the authentication pattern and the endpoint structure -- documentation, not abstraction.

Zechner also pointed out something we'd been experiencing without naming it: MCP servers are hard to extend. You can check out the source and modify it, but then you have to understand their codebase on top of your own. When our MCP server's converter broke, we couldn't just fix the converter -- we'd have needed to fork the project, understand its ADF conversion pipeline, patch it, and maintain our fork. Instead we documented the bugs and worked around them. That's the tax you pay for an abstraction you don't control.

We weren't just paying context overhead. We were paying maintenance overhead, debugging overhead, upgrade-compatibility overhead, and extensibility overhead – all to rent an abstraction that was hiding its own bugs from us, whose outputs weren't composable, and whose tool schemas consumed context whether we used them or not.

A skill is all we need

The replacement architecture has three pieces, same as before, but the bottom layer changed completely.

recipe-atlassian replaced the MCP server. It's a single skill file containing documented curl patterns for every endpoint we use -- authentication, issue CRUD, search, Confluence page operations, file uploads, the works. No SDK, no wrapper functions. Just examples that Claude reads and adapts.

jira-ticket and confluence-page stayed as our team-specific workflow layers, but got cleaner. They stopped referencing MCP tool names and started saying "use the recipe-atlassian skill for all API calls." All the team logic -- project defaults, title conventions, assignee rules, verification workflows -- remained untouched. The skills shed their API plumbing and kept only business logic.

The critical design decisions:

Claude generates ADF inline. Instead of converting Markdown through a buggy middle layer, Claude reads a 200-line ADF schema reference and constructs the JSON directly. Five converter bugs disappeared in one stroke. The same approach works for Confluence -- Claude writes storage format XHTML natively, which gives us access to every Confluence macro including Mermaid diagrams, code blocks with language hints, info panels, and table of contents. The MCP's Markdown conversion couldn't reach most of these.

Every API call is a visible curl command. When something fails, you see the exact request and response:

curl -s -u "${JIRA_USERNAME}:${JIRA_API_TOKEN}" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project": {"key": "PROJ"},
      "summary": "Issue title",
      "issuetype": {"name": "Task"},
      "description": {"version": 1, "type": "doc", "content": [...]}
    }
  }' \
  "${JIRA_URL}/rest/api/3/issue"

No opaque intermediary. No hidden conversion. No wondering which layer broke.

File uploads just work. Curl handles multipart form uploads natively. The thing MCP couldn't do at all became a straightforward curl call with -F "file=@diagram.png". We could finally do full Confluence page updates with Mermaid diagrams in a single workflow.

What the abstraction was hiding

Going direct surfaced things the MCP had been quietly handling -- and sometimes quietly mishandling.

URL format mismatch. JIRA_URL is https://your-org.atlassian.net with no path suffix. CONFLUENCE_URL is https://your-org.atlassian.net/wiki with /wiki included. Our first Confluence curl call produced .../wiki/wiki/api/v2/pages. A 404 on attempt one. Trivial to fix, but we'd never learned the actual URL structure because the MCP constructed URLs for us.

ADF-typed custom fields reject strings. We tried clearing a field by setting it to "". The API said: "Operation value must be an Atlassian Document". The field was ADF-typed -- it needed {"version": 1, "type": "doc", "content": []}. The MCP had been silently coercing types.

Deprecated search endpoint. The old GET /rest/api/3/search is deprecated. The replacement is POST /rest/api/3/search/jql with token-based pagination. The MCP was still on the old endpoint. Going direct put us on the current API.

Every one of these was a thing we should have understood about our own API surface. The MCP wasn't just abstracting the HTTP calls -- it was abstracting our understanding of the system we depend on.

The numbers

Metric MCP (before) Skill (after) Tools registered per session 71 (always loaded) 0 (loaded on demand) Idle context cost ~15-20k tokens 0 tokens External dependencies Docker or uvx, mcp-atlassian PyPI curl, jq (system builtins) Converter bugs/workarounds 6 documented 0 (direct API) Issue creation 2 calls (bug workaround) 1 call File upload support No Yes (native curl) Breaking upgrades absorbed 1 (with full skill rewrite) N/A (we control the patterns)

The zero idle cost is the headline number. Skills load on demand – if a session doesn't touch Jira, zero tokens are spent on Atlassian tooling. With MCP, those 71 tool schemas were in context from session start regardless of whether you needed them.

But the number I care about most is the last one. We will never again have a dependency upgrade break our team's workflow. The curl patterns in our recipe skill talk directly to Atlassian's REST API. If Atlassian changes an endpoint, we update one line in one file. No waiting for an MCP maintainer to ship a fix. No hoping the fix doesn't introduce new converter bugs. No rewriting our workflow skills because tool names changed.

The slow unraveling

Looking back, the trajectory was predictable. MCP gave us fast access to an unfamiliar API, and that was valuable. But as our needs got specific -- team conventions, formatting standards, attachment workflows, custom fields -- the abstraction started fighting us instead of helping us. Each workaround was small. Each bug was tolerable. Each upgrade was absorbable. But they accumulated, and at some point we crossed the line where the MCP was costing more than it saved.

The migration took one session. The six converter workarounds disappeared immediately. File uploads started working. Docker containers stopped piling up. And now when a curl call returns a 400, we see exactly why -- because there's nothing between us and the API but a documented pattern and a shell.

I don't think MCP is wrong. For exploring an unfamiliar API, for broad tool discovery, for integrations maintained by someone else -- it earns its keep. But for a focused integration where you've accumulated a bug list and a workaround file and a history of breaking upgrades? At that point you're not using a tool. You're maintaining a dependency. And the question becomes whether that dependency is giving you more than curl would.

For us, the answer was no.

這個系列前兩集講的是特定的工具——一個監控 skill、一個 triage agent。但說實話，那些只是一段更長旅程的終點，而這段旅程的起點跟所有人一樣：把文字複製貼上到聊天視窗裡，然後祈禱輸出有用。

這一集講的是旅程本身。兩年內，我和 AI 之間的介面換了四次，而每一次換，帶來的改變都比模型本身的進步更大。

人肉剪貼簿

2022 年底、2023 年初。ChatGPT 橫空出世。我記得那段時間在紐約參加一場研討會，講者問台下有沒有人用過好的 chatbot。五百人的會場，舉手的只有兩個。但 ChatGPT 不像我見過的任何 chatbot——它不是在關鍵字上做 pattern matching 然後吐罐頭回覆。它能推理，或者至少表演出一種令人信服的推理。我是真的被震撼到了。

我最先拿它來做的是摘要。一張 Zendesk ticket 進來：900 個字，真正的錯誤訊息埋在第六段，夾在對我們文件的抱怨和要求打電話之間。我把整段複製貼上到 ChatGPT。「幫我摘要這張 ticket，然後草擬一張 Jira story。」出來一份摘要和一張 story。還行。不一致，但還行。

不一致是第一道裂縫。每次輸出的格式都不一樣。LLM 本質上是個隨機過程——同樣的 prompt、同樣的輸入，每次產出不同的結果。當你想在團隊工作流程裡建立在這個基礎上，「每次都不一樣」不是功能，是稅。

於是我做了任何工程師都會做的事：寫下來。一個個人 prompt 收藏夾——按任務分類的文字檔。一個用來摘要 Zendesk ticket。一個用來草擬 Jira story。一個用來寫 incident post-mortem。每個都經過反覆試錯打磨。回頭看，我當時其實是在為一個還不存在的 API 手刻一套個人 SDK，用複製貼上當 transport layer。

這招有用。但也意味著每次互動都是同一套儀式：找到對的 prompt、把 context 複製貼上進去、把輸出複製貼上出來、貼進實際的工具裡、手動修正 LLM 搞錯的部分。我是一塊有主見的人肉剪貼簿。AI 很強大但被隔離了——它住在一個瀏覽器分頁裡，跟每一個真正的工具之間隔著我的剪貼簿這層膜。

當 AI 有了個性

然後來到 persona 時代。Gemini Gems、Claude Projects、ChatGPT custom GPTs。賣點是：不用每次貼 prompt 了，你建一個持久的 context。一個 persona。你描述角色、上傳參考文件、設定語氣。

我建了好幾個。一個 database migration 專用的 persona，熟悉我們的 schema 慣例。一個 support case 分析的 persona，知道我們的產品層級和常見故障模式。一個架構設計的 persona，裝載了我們的 service map 和 API 合約。一致性進步了——support persona 每次都會產出有 acceptance criteria 的 Jira story，因為我告訴它要這樣做。Prompt 消失了，取而代之的是更持久的東西，算有點進步。

但根本的拓撲沒有變。我還是那個 transport layer。把 Zendesk ticket 複製進 support persona，讀輸出，複製進 Jira。AI 更聰明也更一致了，但它還是在聊天視窗裡，而我還是那個在聊天視窗和現實之間搬運資料的人。

我把 persona 分享給團隊，透過連結。他們用了。他們也各自微調了一點，然後我們就有了三份分歧的副本，沒有任何方式可以合併。我們分享知識的方式跟 2004 年分享 Word 文件一樣——寄副本出去，然後祈禱沒人做出衝突的修改。

Tool Layer 到了，然後立刻暴露了真正的問題

MCP 改變了遊戲規則。Model Context Protocol 給了 AI 一個標準化的方式跟實際工具溝通——不是透過我的剪貼簿，而是直接連接。Jira、Confluence、GitHub、AWS、資料庫。隔離解除了。

我從聊天客戶端搬到了 Cursor 和 Claude Code。不再把 support case 複製進聊天視窗了，我可以直接說「讀這張 Zendesk ticket 然後建一張 Jira story」，agent 會透過 Zendesk 整合讀 ticket，透過 Jira MCP tool 建 story，直接填入欄位。沒有剪貼簿。沒有複製貼上。

大概有兩個禮拜，我以為這就是終極形態了。然後格式問題又回來了。

MCP 讓 AI 可以使用工具。但它沒有讓 AI 知道你的團隊怎麼使用這些工具。我們團隊對 SSO 子系統有特定的 component tag。我們對來自 support case 的 story 和來自內部規劃的 story 有不同的命名慣例。Story point 欄位是 customfield_10004，不是每個 LLM 第一次都會猜的那個比較直覺的欄位名。

Agent 可以建 Jira ticket。但建出來是錯的。Component 錯、label 格式錯、story point 填錯欄位。每次修正都是我在對話裡打的一句 prompt，下一個 session 就忘了。我又回到了記 prompt 的日子——不是因為 AI 缺乏能力，而是因為它缺乏我們團隊的 context。

Mario Zechner 說得好：「與其爭論 MCP 還是 CLI，不如開始打造更好的工具。Protocol 只是水管。」他說得對。他的 benchmark 顯示，設計良好的情況下，MCP 和純 CLI 工具的表現一模一樣——一個 225 token 的 CLI wrapper 配上好的 README，勝過一個 18,000 token 但文件寫得爛的 MCP server。問題從來不是 protocol。是團隊怎麼把自己的慣例編碼進給 agent 用的工具裡。MCP 是工具供應商的介面。它暴露的是 Jira 能做什麼。它對於 Jira 應該怎麼被一個三人 SSO 團隊使用——用什麼 component tag、什麼 story 格式——一個字都沒說。那個落差——capability 和 convention 之間的——才是所有摩擦真正住的地方。

從快捷鍵到可以 Commit 的東西

Custom command 是第一次嘗試填補這個落差。Claude Code 裡的 slash command：你把一段長 prompt 寫在檔案裡，給它一個名字，用 /my-command 呼叫。Prompt 載入，agent 照指令走，你不用每個 session 重新打一次慣例就能拿到一致的輸出。

我建了一堆。/create-support-ticket 包含了我們所有 Jira 慣例。/write-postmortem 有我們的 incident report 結構。/draft-epic 知道我們怎麼把 feature 拆成 story。更好了。但很僵硬。

Custom command 就是一段加了捷徑的長 prompt。它不能動態引用外部檔案。它不能根據輸入類型調整。而且最關鍵的，agent 不能自己發現它——你必須知道這個 command 存在然後明確地呼叫它。如果一個隊友在處理 incident 但不記得有 /write-postmortem 這個東西，他就會從頭寫 post-mortem。知識被編碼了，但不可被發現。

然後 skill 出現了，而這裡我需要誠實地說它是什麼、不是什麼。

Skill 在 Claude Code 裡是一組指令、references 和 sub-command 的集合，agent 可以自動發現並執行。當 agent 看到一個任務符合某個 skill 的描述，它可以在使用者沒有明確呼叫的情況下載入並執行。Skill 可以引用外部檔案——我們的 Jira component mapping、incident severity rubric——而且它可以呼叫 MCP tool，所以整個鏈條就接上了：skill 編碼我們團隊的慣例，MCP tool 把它們執行在真實系統上。

我的工作流程變成：/jira-skill "customer reports SAML integration broken, see Zendesk #4521"。Skill 偵測到這是一張 support 來源的 ticket，載入 convention reference，套用正確的 component tag 和 label 格式，填入 customfield_10004，然後呼叫 Jira MCP tool。一次呼叫，輸出正確，不用修正。

但真正的價值不在呼叫本身。而是當 agent 在自主執行一個更大的任務、遇到一個 skill 能處理的子任務時會發生什麼。它找到 skill、載入它、使用它。慣例在我不在 loop 裡的情況下被套用。團隊的知識不只是被編碼了；它可以被 agent 當作一個可組合的原語來使用。

Skill 一開始確實是特定 agent 專用的，但生態系正在趨同。像 Vercel 的 skills CLI 這類專案已經可以把同一個 skill 定義分發到四十多種 agent 上，從 Claude Code 到 Cursor 到 Gemini CLI。基本格式——一個 Markdown 檔案加上名稱、描述和指令——正在變成一個共享的原語。進階功能在不同 agent 間仍有差異，但核心模式是可攜的，而且越來越可攜。

改變一切的那次 Commit

故事在這裡繞回前兩集。

Episode 1 的監控 skill 和 Episode 2 的 triage agent 之所以特別，不是因為它們用了 AI。是因為它們被 commit 進了 repository。它們活在版本控制裡。它們透過 pull request 演化。可以 review、可以 diff、可以執行。

以前分享 AI context 意味著傳一個 Gem 或 Project 的連結。現在意味著把 skill commit 進 repo。新工程師可以讀 skill 理解團隊怎麼處理 support case，或者直接跑它，開箱即用地拿到正確的行為。

當一個隊友發現我們的 triage skill 缺少 ECS deployment 檢查——Episode 2 的事——我們沒有更新 wiki 頁面，也沒有發一則兩天後就被淹沒的 Slack 訊息。我們更新了 skill 然後 commit 了變更。Diff 講述了故事：「新增 ECS deployment status 檢查作為第一個調查步驟，因為 Incident #5 顯示 deployment 變更是最常見的 root cause。」營運知識，有版本控制、可 review、可立即執行。

Zechner 提到，用 ad-hoc 的工具，「你必須自己想出一套結構來建造和維護它們。」對一個人開發來說，這種自由是資產。對一個團隊來說，它是負債。三個人各自維護 ad-hoc 工具但沒有共享慣例，會以跟我們當初 persona 分歧完全一樣的方式分歧。共享 repo 裡有版本控制的 skill，是讓我們保持一致的強制函數。

壓縮一下這個演化：複製貼上、然後 persona、然後 MCP、然後 skill。每一步都壓縮了意圖和行動之間的一層摩擦。複製貼上用一塊人肉剪貼簿隔開它們。Persona 減少了 prompt 負擔但人類還是 transport。MCP 移除了 transport 但沒帶走慣例。Skill 編碼了慣例，並讓它們可以被發現。

介面才是瓶頸

過去兩年我一直假設限制因素是模型智慧。更好的模型會產出更好的結果。狹義上來說這沒錯。但真正改變我日常工作的進步，不在智慧。在介面。

從複製貼上到 persona，每個任務省了五分鐘。從 persona 到 MCP，省了十分鐘。從 MCP 到 skill，也有省時間——但最重要的是提升的一致性，而一致性才是三個人用同一套慣例跑正式環境時真正重要的東西。時間節省線性累積。一致性節省效益指數擴大，因為每一個不一致都會產生下游修正，而那些修正又會製造自己的不一致。

我的 prompt 收藏夾消失了。不是被刪除——是被遺棄。複製貼上成為時代的化石。裡面的知識已經遷移到 commit 進 repository 的 skill 裡，agent 可以發現它們，每一次 incident 和 sprint 都在改善它們。全團隊用同一套 skill，當其中一個人教了 skill 新東西，下一次執行所有人都受益。

這個系列裡的典範轉移不是「AI 能做事了」。轉移在於，人類意圖和機器行動之間的介面，從一個多步驟、有損耗、手動的過程，坍縮成了一個看起來像 function call、感覺像在跟一個讀完了你從來沒寫的文件的隊友說話的東西。

我從來沒寫那些文件，因為我從來沒有時間。現在我不用寫了。Skill 就是文件。它們只是碰巧還能執行。

The previous two episodes in this series were about specific tools — a monitoring skill, a triage agent. But if I am honest, those were endpoints in a longer journey that started the same way it started for everyone: copying text into a chat window and hoping the output was useful.

This episode is about the journey itself. How the interface between me and AI changed four times in two years, and why each change mattered more than any improvement in the models.

The Human Clipboard

Late 2022, early 2023. ChatGPT exists. I remember attending a conference in New York around that time where a speaker asked the room if anyone had used a good chatbot. Two hands went up out of five hundred people. But ChatGPT was not like any chatbot I had met — it was not pattern-matching on keywords and returning canned responses. It could reason, or at least perform a convincing impression of reasoning. I was genuinely mind-blown.

The first thing I used it for was summarizing. A Zendesk ticket comes in: 900 words burying the actual error in paragraph six between a complaint about our documentation and a request for a phone call. I copy the entire thing into ChatGPT. "Summarize this and draft a Jira story." Out comes a summary and a story. Not bad. Not consistent, but not bad.

The inconsistency was the first crack. Every output had a different format. LLMs are stochastic — the same prompt on the same input produces different outputs, and when you are trying to build a team workflow around them, "different every time" is not a feature. It is a tax.

So I did what any engineer does: I wrote it down. A personal prompt library — text files organized by task. One for summarizing Zendesk tickets. One for drafting Jira stories. One for writing incident post-mortems. Each refined through trial and error. I was building a personal SDK for an API that did not exist yet, using copy-paste as the transport layer.

This worked. It also meant that every interaction followed the same ritual: find the right prompt, copy-paste the context in, copy-paste the output out, paste it into the actual tool, manually fix whatever the LLM got wrong. I was a human clipboard with opinions. The AI was powerful but quarantined — living in a browser tab, separated from every real tool by the membrane of my clipboard.

When AI Got a Name Tag

Then came the persona era. Gemini Gems, Claude Projects, ChatGPT custom GPTs. The pitch: instead of pasting a prompt every time, you build a persistent context. A persona. You describe the role, upload reference documents, set the tone.

I built several. A database migration persona that knew our schema conventions. A support case persona that knew our product tiers and failure modes. An architecture persona with our service map and API contracts. Consistency improved — the support persona always produced Jira stories with acceptance criteria because I told it to. The prompts were gone, replaced by something more durable. Progress.

But the fundamental topology had not changed. I was still the transport layer. Copy the Zendesk ticket into the support persona, read the output, copy it into Jira. The AI was smarter and more consistent, but it was still in a chat window, and I was still moving data between the chat window and reality.

I shared my personas with my team via links. They used them. They also modified them slightly for their own preferences, and now we had three divergent copies with no way to reconcile them. We were sharing knowledge the way people shared Word documents in 2004 — by emailing copies and hoping nobody made a conflicting edit.

The Tool Layer Arrives, and Immediately Reveals the Real Problem

MCP changed the game. Model Context Protocol gave AI a standardized way to talk to actual tools — not through my clipboard, but directly. Jira, Confluence, GitHub, AWS, databases. The quarantine was lifted.

I moved from chat clients to Cursor and Claude Code. Instead of copying a support case into a chat window, I could say "read this Zendesk ticket and create a Jira story" and the agent would read the ticket, create the story through the Jira MCP tool, and populate the fields directly. No clipboard. No copy-paste.

For about two weeks, I thought this was the endgame. Then the format problem resurfaced, wearing a different hat.

MCP gives AI access to tools. It does not give AI access to your team's conventions for using those tools. Our team uses specific component tags for SSO subsystems. We have naming conventions for stories that originate from support cases versus internal planning. The story point field is customfield_10004, not the more intuitive field name that every LLM guesses first.

The agent could create Jira tickets. It created them wrong. Wrong component. Wrong label format. Story points in the wrong field. Every correction was a prompt typed into the conversation that would be forgotten by the next session. I was back to remembering prompts — not because the AI lacked capability, but because it lacked my team's context.

Mario Zechner put it well: "Maybe instead of arguing about MCP vs CLI, we should start building better tools. The protocol is just plumbing." He is right. His benchmarks show that MCP and plain CLI tools perform identically when well-designed — a 225-token CLI wrapper with a good README outperforms an 18,000-token MCP server with poor documentation. The problem was never the protocol. It was how teams encode their conventions into the tools they give their agents. MCP is the tool vendor's interface. It exposes what Jira can do. It says nothing about what Jira should do for a three-person SSO team at Ubiquiti that uses specific component tags and a specific story format. That gap — between capability and convention — is where all the friction lives.

From Shortcuts to Something That Commits

Custom commands were the first attempt to close the gap. Slash commands in Claude Code: you write a long prompt in a file, give it a name, and invoke it with /my-command. The prompt loads, the agent follows the instructions, and you get consistent output without re-typing your conventions every session.

I built a bunch. /create-support-ticket contained all our Jira conventions. /write-postmortem had our incident report structure. /draft-epic knew how we decompose features into stories. Better. But rigid.

A custom command is a long prompt with a shortcut. It cannot reference external files dynamically. It cannot adapt based on input type. And critically, the agent cannot discover it on its own — you have to know the command exists and invoke it explicitly. If a teammate is triaging an incident and does not remember that /write-postmortem exists, they write the post-mortem from scratch. The knowledge is encoded but not discoverable.

Then skills arrived, and here I need to be honest about what they are and what they are not.

A skill, in Claude Code, is a bundle of instructions, references, and sub-commands that an agent can discover and execute. When the agent sees a task that matches a skill's description, it can load it without the user explicitly invoking it. The skill can reference external files — our Jira component mapping, our incident severity rubric — and it can call MCP tools, so the chain completes: the skill encodes our team's conventions, and the MCP tools execute them against real systems.

My workflow became: /jira-skill "customer reports SAML integration broken, see Zendesk #4521". The skill detects a support-originated ticket, loads the convention reference, applies the right component tags and label format, populates customfield_10004, and calls the Jira MCP tool. One invocation, correct output, no corrections.

But the real value is what happens when the agent is working autonomously on a larger task and encounters a subtask a skill can handle. It finds the skill, loads it, uses it. The conventions are applied without me being in the loop. The team's knowledge is not just encoded; it is available to the agent as a composable primitive.

Skills started as agent-specific, but the ecosystem is converging. Projects like Vercel's skills CLI already distribute the same skill definition across forty-plus agents, from Claude Code to Cursor to Gemini CLI. The basic format — a Markdown file with a name, a description, and instructions — is becoming a shared primitive. Advanced features still vary by agent, but the core pattern is portable, and getting more so.

The Commit That Changed Everything

Here is where the story loops back to the first two episodes.

The monitoring skill from Episode 1 and the triage agent from Episode 2 are not special because they use AI. They are special because they are committed to the repository. They live in version control. They evolve through pull requests. They are reviewable, diffable, and executable.

Previously, sharing AI context meant sending a link to a Gem or a Project. Now it means committing a skill to the repo. A new engineer can read the skill and understand how the team handles support cases, or just run it and get the right behavior out of the box.

When a teammate found the ECS deployment gap in our triage skill — Episode 2 — we did not update a wiki page or send a Slack message that would scroll off screen in two days. We updated the skill and committed the change. The diff tells the story: "Added ECS deployment status check as first investigation step after Incident #5 revealed deployment changes are the most common root cause." Operational knowledge, version-controlled, reviewable, and immediately executable.

Zechner notes that with ad-hoc tools, "you will have to come up with a structure for how you build and maintain those tools yourself." For a solo developer, that freedom is an asset. For a team, it is a liability. Three people maintaining ad-hoc tools without shared conventions will diverge in exactly the same way our personas diverged back in the chat era. Version-controlled skills in a shared repo are the forcing function that keeps us aligned.

The shift, compressed: copy-paste, then personas, then MCP, then skills. Each step collapsed a layer of friction between intent and action. Copy-paste separates them by a human clipboard. Personas reduce the prompt overhead but keep the human as transport. MCP removes the transport but not the conventions. Skills encode the conventions and make them discoverable.

The Interface Was the Bottleneck

I spent the last two years assuming that the limiting factor was model intelligence. Better models would produce better output. That is true, narrowly. But the improvements that actually changed my daily work were not about intelligence. They were about interface.

The jump from copy-paste to personas saved me five minutes per task. The jump from personas to MCP saved me ten. The jump from MCP to skills saves time too, but most importantly — it saved me consistency, which is the thing that actually matters when three people are trying to operate a production system using the same conventions. Time savings compound linearly. Consistency savings compound geometrically, because every inconsistency creates downstream corrections.

My prompt library is gone. Not deleted — abandoned. A fossil record of the copy-paste era. The knowledge it contained has migrated into skills committed to the repository, discoverable by agents, and improving with every incident and sprint. The whole team uses the same skills, and when one of us teaches a skill something new, all of us benefit on the next run.

The paradigm shift in this series is not "AI can do things." The shift is that the interface between human intent and machine action collapsed from a multi-step, lossy, manual process into something that looks like a function call and feels like talking to a teammate who has read all the documentation you never wrote.

I never wrote that documentation because I never had time. Now I do not have to. The skills are the documentation. They just happen to also execute.

Three weeks after I built the monitoring skill from Episode 1, our SSO service started acting up — specifically, passkey login on a new Android app that had just gone to market in beta. Not a full outage. The insidious kind of broken where most authentication methods work and one doesn't, so the bug reports trickle in slowly and you spend the first twenty minutes wondering if it is a real incident or just a beta-quality client doing beta-quality things.

It was real.

Passkey authentication was failing intermittently on the beta Android app. Brian built the WebAuthn flow eight months ago — I reviewed every PR but never did the hands-on staging testing, so my understanding was architectural, not visceral. Brian was on vacation in Hokkaido, unreachable in every way that matters. The root cause, as we would later discover, was on us: the beta client had been configured with the wrong passkey origin, and WebAuthn does not forgive origin mismatches.

This is the part of incident response nobody talks about in post-mortems: the knowledge bottleneck is not a process failure. It is a structural inevitability. Brian built the passkey feature. He knows which database tables it touches, which Athena queries reveal its failure modes, which CloudWatch metrics actually matter versus which ones look alarming but mean nothing. That knowledge lives in his head, accumulated over months of debugging sessions and late-night deploys. I know the architecture from code review, but knowing how something is designed and knowing how it breaks are two very different things. The gap between reviewing a PR and debugging a production incident is the gap between reading a map and navigating a city at night.

So here is what happens in the old world — briefly, because if you have ever been the person on the team who has to debug something they did not build, you already know. I open six browser tabs. I dig through Brian's old Athena queries in our shared workspace, trying to figure out which ones are still relevant. I read CloudWatch metrics I half-understand, pattern-matching against what I remember from code review. Steven, our designated incident liaison, watches my screen because he wants to learn, but I am too deep in query results to narrate what I am doing — partly because I am still figuring it out myself. The stakeholder update does not get sent. The liaison role is a polite fiction we maintain because the incident response template says we need one. The person trying to debug is too busy debugging to communicate, and the person who should communicate does not have enough context to say anything useful.

That is the structural problem. Vendor triage copilots exist — PagerDuty, Datadog, others — but they optimize for their own telemetry stack. Ours needed to reason across CloudWatch, application logs, deployment history, and domain-specific Athena queries simultaneously, in a way only a custom agent with full context of our stack could do. Everything that follows is an attempt to break the knowledge bottleneck with that agent.

The Fear Is Reasonable. The Boundary Is Simple.

The fear of letting AI touch infrastructure is not theoretical. Earlier this month, Amazon held a company-wide engineering meeting after a pattern of outages tied to AI-assisted code changes — including a six-hour shopping site outage on March 5th that knocked out checkout, login, and product pricing. Their internal briefing described "high blast radius" incidents linked to "Gen-AI assisted changes." Amazon's response was to require senior engineer sign-off on all AI-assisted production changes. The instinct everywhere is the same: AI near infrastructure is dangerous, so add friction.

I understand the caution. I have the same fear. The last thing I want during an active incident is an AI agent deciding to helpfully restart the database or modify a security group.

But Amazon's problem — and the instinct to add blanket friction — conflates two very different things. There is an enormous gap between reading a CloudWatch metric and modifying an Auto Scaling group. One is observation. The other is action. We do not refuse to let junior engineers look at production dashboards because we are afraid they might accidentally click "Terminate Instance."

The fix was a service account with read-only permissions. An IAM policy: CloudWatch GetMetricData, RDS Performance Insights reads, Athena queries against read-only analytics tables, ALB and WAF metric reads, CloudTrail lookups. No PutMetricAlarm. No ModifyDBInstance. Nothing that modifies state.

This turns out to be the only safety boundary that matters in practice. Not "can the AI access infrastructure" but "can the AI change infrastructure." Read-only access gives you an extra pair of eyes without giving you an extra pair of hands. I brought the policy back to the platform team, they audited it, added a few explicit denies, and agreed to a trial. The trial is still running. Nobody has asked me to stop.

Fourteen Minutes

The second incident arrived on a Tuesday. Passkey authentication failures again, this time concentrated on Android beta users in specific regions. I pasted the CloudWatch alarm payload, the first three bug reports from the beta channel, and the service name into the triage agent. One command: /triage-incident --context <paste>.

The agent spawned three parallel investigation threads — service-level metrics, infrastructure health, and passkey-specific queries — and reported back while I was still waiting for the RDS Performance Insights console to render. (The console takes a genuinely impressive amount of time, as if each pixel is hand-painted by an AWS intern.)

The infrastructure thread found it. Primary RDS read IOPS at 4x normal. Connection pool at 89%. The WebAuthnCredentialLookup query had gone from a P95 of 12ms to 340ms. The agent correlated this with a CloudTrail entry showing a compliance batch job — quarterly, full table scans on the same tables the passkey lookup uses — had started twenty minutes before the first beta user report.

Fourteen minutes from alert to root cause. I had not typed a single Athena query.

Here is what mattered more than the speed: I had nothing to do with my hands. The agent was investigating. My normal instinct — run queries, check dashboards, build a mental model — was already being done. So I did the thing that incident response frameworks have begged me to do for years. I communicated.

I spun up a second agent session connected to Atlassian. Incident report created, findings fed in as they arrived. When we confirmed the batch job was the cause, the compliance team got tagged within minutes instead of the usual "someone remembers to Slack them thirty minutes later." Steven was reading the triage output alongside me, following the diagnostic reasoning as structured narrative rather than trying to parse my frantic tab-switching. He started asking questions: "Why did it check DynamoDB latency separately from RDS?" Because the passkey flow hits both stores, and you need to isolate which layer is the bottleneck. He was learning the reasoning, not by watching me type too fast to follow, but by reading an investigation that explained itself.

Four stakeholder updates sent during the incident. In the old world, that number would have been zero.

Total time from alert to mitigation: twenty-two minutes. I started to feel like the tool was trustworthy. That feeling was about to be corrected.

When the Agent Was Wrong, and Why That Was the Point

The third incident, two weeks later, the agent got it wrong. Elevated 5xx on the token exchange endpoint. The agent confidently blamed DynamoDB GSI throttling — a metric spike that correlated perfectly with the error onset. I almost acted on it. But the GSI was at 40% of provisioned capacity. Nowhere near throttling. The agent had pattern-matched on "metric went up at the same time as errors" without asking whether the magnitude was enough to matter. The real cause was a rate limiter typo in that morning's deploy — 50 requests per second instead of 500. One missing zero, sitting in the deployment diff the agent never checked.

Eighteen minutes lost. Not catastrophic, but enough to change how we used the tool. We stopped treating the agent's output as a verdict and started treating it as a brief — hypotheses with evidence, reviewed by a human who asks: does the anomaly actually explain the impact? What changed recently? After the failure, I updated the skill to check deployment history first and to validate metric thresholds against provisioned capacity, not just look for spikes. Steven caught another gap in the fourth incident: no ECS deployment status check. He told me, I updated the skill.

The pattern became clear. Every time the agent was wrong or incomplete, I just told it: "You missed the deployment history. Update the triage skill so that checking recent changes is always the first investigation thread." The agent rewrote its own skill. Next time I told it: "When you check DynamoDB metrics, compare consumed capacity against provisioned capacity — a spike means nothing if you are at 40% of your limit." The agent updated itself again. Steven found the ECS gap, told me, and I relayed it the same way. One sentence, and the skill absorbed the lesson.

No manual editing of config files. No writing runbook entries after the fact. I just talked to the agent about what it got wrong, and it fixed its own playbook. The corrections accumulated. The skill got committed to the repo, and the diff tells the story: each change traces back to a specific incident and a specific mistake. It is a changelog of the team's diagnostic intelligence, maintained not by discipline but by the natural pressure of real incidents.

The Fifth Incident

By the fifth incident, those one-sentence corrections had compounded into something I did not expect. The skill checked deployment history first. It validated metric thresholds against provisioned capacity. It checked ECS deployment status. All lessons it learned from being told, once, what it missed. I barely intervened during the triage phase. The agent was not perfect — it still flagged irrelevant metrics occasionally, and its severity assessments ran a notch too high. But it was operating at the level of a teammate who had been on the team for a year, not the blank-slate tool it was on day one.

Steven used it solo last week. An alert fired for elevated 401 responses on the token refresh endpoint. He ran the triage skill. It checked recent deployments first (none), swept infrastructure metrics, then went narrow on the token validation subsystem. Twelve minutes to root cause — an upstream identity provider had changed their JWKS endpoint response format, breaking our key rotation. Steven filed the incident report, communicated with stakeholders, and coordinated the fix. He did not need me. He did not Slack me. I found out from the post-mortem document the next morning.

That is the moment I knew the structural problem was actually broken. Not dented, not mitigated. Broken. Steven ran an incident end-to-end using a skill that had learned from every previous mistake — mistakes I had simply talked it through, one sentence at a time.

What the Numbers Say

I want to be honest about measurement. We did not run a controlled experiment. We do not have clean before-and-after metrics because the "before" was not instrumented. What we have is timestamps from Slack messages, incident reports, and my own notes.

Before the triage agent, our median time from alert to root cause identification — across the six incidents I can reconstruct from 2025 — was roughly seventy minutes. The range was thirty minutes (for problems I had seen before and could diagnose from muscle memory) to four hours (for novel failure modes that required building understanding from scratch).

With the triage agent, across five incidents, the median is eighteen minutes. The range is twelve to twenty-eight. The twenty-eight-minute outlier was the third incident, where the agent was wrong and we lost time on a false lead.

The number I care about more: stakeholder updates sent during the active incident phase. Before: a median of one, usually sent after the fix was already in progress. After: a median of four, with the first one going out within ten minutes of the alert. That is the communication unlock. The triage agent did not just speed up diagnosis. It freed the humans to do the part of incident response that humans are actually good at and that actually matters to the people waiting for answers.

What the Engineer Should Have Been Doing All Along

The conventional accounting of incident cost focuses on downtime minutes. Those matter. But the hidden cost — the one that compounds quarter over quarter — is the knowledge monopoly. Every incident that only one person can triage makes that person more indispensable and the team more fragile. The experienced engineer becomes a single point of failure not because they want to be, but because incident work is inherently apprenticeship-based, and there are never enough incidents to train everyone, and the incidents that do occur are too urgent to use as teaching moments.

The triage agent did not replace me. It revealed what I should have been doing all along.

All those years of incident response, I thought my job was to diagnose the problem. To be the person who knew the queries, knew the metrics, knew the system's failure modes — or at least knew enough to muddle through when the person who really knew was unavailable. That was the expectation. But diagnosing the problem was never the hard part for the team — it was only the hard part because the knowledge was locked in one person's head, and that person was not always in the room. The actual hard part, the part that affected customers and stakeholders and the business, was communicating clearly under pressure, coordinating across teams, and making judgment calls about severity and mitigation trade-offs. I was not doing any of that because I was too busy being the human query engine.

The agent took over the query engine role. What remained was the work that actually mattered: talking to people, making decisions, and teaching others. It turns out that the "hero engineer" was not heroic. The hero engineer was a bottleneck who happened to type fast.

I do not know what the sixth incident will teach the skill. That is the point. The skill does not need to be complete on day one. It just needs to be better after each incident than it was before, and the team needs to trust it enough to use it and skeptical enough to correct it. So far, both of those bars have been easy to clear.

[以下故事人名以及事件都為了保護隱私而有所虛構]

第一集的監控 skill 做好三週後，我們的 SSO 服務出了問題——具體來說，是一個剛上市 beta 版的 Android app 上的 passkey 登入。不是全面中斷，而是那種最陰險的壞法：大部分驗證方式正常運作，只有一種不行。Bug report 零零星星地進來，你頭二十分鐘都在猶豫這到底是真正的事故，還是 beta 品質的 client 在做 beta 品質的事。

是真的。

Passkey 驗證在 beta Android app 上間歇性失敗。Brian 八個月前寫了 WebAuthn 流程——每個 PR 我都 review 過，但從沒親手在 staging 環境測試，所以我的理解是架構層面的，不是體感層面的。Brian 正在北海道度假，完全失聯。後來查出來的根本原因在我們這邊：beta client 配了錯誤的 passkey origin，而 WebAuthn 對 origin mismatch 毫不寬容。

這是 post-mortem 裡沒人會講的那個部分：知識瓶頸不是流程問題，而是結構性的必然。Brian 做了 passkey 功能。他知道碰了哪些資料庫 table、哪些 Athena query 能揭露失敗模式、哪些 CloudWatch metric 真正重要而哪些只是看起來嚇人卻什麼都不代表。這些知識全裝在他腦袋裡，是好幾個月的除錯和半夜部署一點一滴累積的。我從 code review 了解架構，但知道一個東西怎麼設計和知道它怎麼壞掉，是完全不同的兩回事。review 一個 PR 跟在 production 除錯之間的距離，就像看 Google Maps 跟半夜在陌生巷弄裡找路的距離。

接下來在舊世界裡會發生什麼——簡短帶過，因為如果你曾經是團隊裡那個必須除錯自己沒寫的東西的人，你已經知道了。我打開六個瀏覽器分頁。翻 Brian 的舊 Athena query，試著搞清楚哪些還有用。看著我一知半解的 CloudWatch metric，用 code review 的記憶做模式比對。Steven，我們指定的事故聯絡人，在看我的螢幕因為他想學，但我正深陷在 query 結果裡沒辦法邊做邊講——一部分原因是我自己都還在搞清楚狀況。利害關係人更新沒發出去。聯絡人角色只是照著流程擺出來的樣子，因為事故應變模板說我們需要一個。正在除錯的人忙到沒空溝通，而應該溝通的人沒有足夠的脈絡去說出任何有用的話。

這就是結構性問題。市面上有 vendor triage copilot——PagerDuty、Datadog 等等——但它們都是針對自家遙測堆疊做最佳化。我們需要的，是一個能同時跨 CloudWatch、應用程式 log、部署歷史和特定領域 Athena query 做推理的東西，而且只有一個完整了解我們技術堆疊的自建 agent 才做得到。以下所有事情，都是嘗試用那個 agent 打破知識瓶頸。

恐懼是合理的。邊界也很簡單。

讓 AI 碰基礎設施的恐懼不是杞人憂天。這個月稍早，Amazon 召開了一場全公司工程會議，因為一連串與 AI 輔助程式碼變更相關的故障——包括三月五日一場長達六小時的購物網站中斷，結帳、登入和商品定價全部癱瘓。內部簡報描述了與「Gen-AI assisted changes」相關的「high blast radius」事故。Amazon 的對策是要求所有 AI 輔助的 production 變更都需要 senior engineer 簽核。所有人的直覺都一樣：AI 靠近基礎設施很危險，所以加阻力。

我理解這份謹慎。我有同樣的恐懼。在活躍事故中，我最不想看到的就是一個 AI agent 自作主張地重啟資料庫或改 security group。

但 Amazon 的問題——以及那種加全面阻力的直覺——混淆了兩件截然不同的事。讀一個 CloudWatch metric 和修改一個 Auto Scaling group 之間有巨大的鴻溝。一個是觀察，另一個是行動。我們不會因為害怕 junior engineer 不小心按到「Terminate Instance」就不讓他們看 production dashboard。

解法是一個唯讀權限的 service account。一條 IAM policy：CloudWatch GetMetricData、RDS Performance Insights 讀取、對唯讀分析 table 的 Athena query、ALB 和 WAF metric 讀取、CloudTrail lookup。沒有 PutMetricAlarm。沒有 ModifyDBInstance。任何會改變狀態的操作都不行。

這在實務上是唯一重要的安全邊界。不是「AI 能不能存取基礎設施」，而是「AI 能不能改變基礎設施」。唯讀存取讓你多一雙眼睛，但不多一雙手。我把 policy 帶回 platform team，他們稽核後加了幾條明確的 deny，同意試行。試行至今仍在進行，沒有人要求我停下來。

十四分鐘

第二次事故發生在一個星期二。Passkey 驗證失敗再次出現，這次集中在特定地區的 Android beta 用戶。我把 CloudWatch alarm payload、beta channel 的前三則 bug report 和服務名稱貼進 triage agent。一個指令：/triage-incident --context <paste>。

Agent 同時啟動了三條並行調查線——服務層 metric、基礎設施健康度和 passkey 專屬 query——在我還在等 RDS Performance Insights 主控台渲染完成時就回報了。（那個主控台載入的時間長得令人印象深刻，彷彿每個像素都是 AWS 實習生手繪的。）

基礎設施那條線找到了。Primary RDS read IOPS 是正常值的四倍。Connection pool 到 89%。WebAuthnCredentialLookup query 的 P95 從 12ms 飆到 340ms。Agent 把這些跟 CloudTrail 的一筆記錄做了關聯——一個季度合規批次作業，對 passkey lookup 用的同一批 table 做全表掃描——在第一則 beta 用戶回報前二十分鐘啟動。

從警報到找到根本原因，十四分鐘。我一個 Athena query 都沒打。

但比速度更重要的是：我的手居然空了下來。Agent 在調查。我平常的直覺反應——跑 query、盯 dashboard、在腦中拼湊模型——已經有人在做了。所以我做了事故應變框架多年來一直拜託我做的事。我去溝通。

我開了第二個 agent session 連接 Atlassian。事故報告建立好了，調查結果一出來就灌進去。當我們確認批次作業是原因時，合規團隊在幾分鐘內就被 tag 到了，而不是通常的「某人在三十分鐘後想起來要 Slack 他們」。Steven 跟我一起看 triage 的輸出，他是在看一個有結構的診斷敘述，而不是試圖解讀我瘋狂切換分頁的動作。他開始問問題：「為什麼它把 DynamoDB latency 跟 RDS 分開檢查？」因為 passkey 流程兩邊都會打，你需要隔離瓶頸在哪一層。他在學推理過程，不是靠看我打字打到跟不上，而是讀一份會自我解釋的調查報告。

事故期間發出四則利害關係人更新。在舊世界，那個數字會是零。

從警報到緩解的總時間：二十二分鐘。我開始覺得這個工具值得信賴。這份信心很快就被打臉了。

Agent 判斷錯誤的那次，以及為什麼那才是重點

第三次事故，兩週後，agent 搞錯了。Token exchange endpoint 出現 5xx 升高。Agent 很有信心地歸咎於 DynamoDB GSI throttling——一個與錯誤開始時間完美相關的 metric spike。我差點就照著做了。但那個 GSI 只用了 provisioned capacity 的 40%，離 throttling 遠得很。Agent 做了「metric 跟錯誤同時上升」的模式比對，卻沒問幅度夠不夠大。真正的原因是那天早上部署裡一個 rate limiter 的 typo——每秒 50 個 request 而不是 500 個。差一個零，就在 agent 從沒去看的 deployment diff 裡。

繞了十八分鐘的彎路。不算致命，但夠我們痛定思痛。從那之後我們不再把 agent 的輸出當定論，而是當偵查報告——附帶證據的假說，由人來審視追問：這個異常真的能解釋影響嗎？最近改了什麼？失敗後我更新了 skill：先檢查部署歷史，並且驗證 metric threshold 要跟 provisioned capacity 比，不能只看 spike。Steven 在第四次事故中抓到另一個缺漏：沒有檢查 ECS deployment status。他告訴我，我更新了 skill。

規律浮現了。每次 agent 判斷錯誤或不完整，我只需要告訴它：「你漏了部署歷史。更新 triage skill，讓檢查近期變更永遠是第一條調查線。」Agent 改寫了自己的 skill。下次我告訴它：「檢查 DynamoDB metric 時，要把 consumed capacity 跟 provisioned capacity 做比較——如果你只用了 40% 的額度，spike 什麼都不代表。」Agent 又更新了自己。Steven 發現 ECS 的缺漏，告訴我，我用同樣的方式轉達。一句話，skill 就吸收了教訓。

不用手動改設定檔。不用事後補 runbook。我就是跟 agent 聊它哪裡搞砸了，它自己就把 playbook 改好。修正一路疊加。Skill 被 commit 進 repo，diff 就是故事：每個改動都追溯到一次特定的事故和一個特定的錯誤。那是團隊診斷功力的 changelog，靠的不是誰有紀律去維護，而是每次真實事故逼出來的。

第五次事故

到了第五次事故，那些一句話的修正已經滾成了我始料未及的雪球。Skill 會先檢查部署歷史。會把 metric threshold 跟 provisioned capacity 做比較。會檢查 ECS deployment status。全都是被告知一次就學會的教訓。在 triage 階段我幾乎不用介入。Agent 並不完美——偶爾還是會標記無關的 metric，嚴重性評估也偏高一檔。但它的表現已經像一個在團隊待了一年的人，不再是第一天那個什麼都不懂的菜鳥工具。

Steven 上週獨立使用了它。一個警報觸發：token refresh endpoint 的 401 response 升高。他跑了 triage skill。Skill 先檢查近期部署（沒有），掃過基礎設施 metric，然後縮小範圍到 token validation 子系統。十二分鐘找到根本原因——上游 identity provider 更改了 JWKS endpoint 的回應格式，破壞了我們的 key rotation。Steven 建了事故報告、跟利害關係人溝通、協調修復。他不需要我。他沒有 Slack 我。我是隔天早上從 post-mortem 文件裡才知道的。

那個瞬間我知道，結構性問題真的被解掉了。不是緩解，是破局。Steven 端到端地處理了一次事故，用的是一個從每次先前錯誤中學習過的 skill——而那些錯誤，我只是一句一句地講給它聽。

數字怎麼說

量測這件事，我想講白一點。我們沒有跑對照實驗。我們沒有乾淨的前後比較 metric，因為「之前」根本沒有被 instrument。我們有的是 Slack 訊息、事故報告和我自己筆記裡的時間戳。

在 triage agent 之前，我們從警報到找到根本原因的中位數——根據我能重建的 2025 年六次事故——大約是七十分鐘。快的三十分鐘（見過的問題，靠肌肉記憶就能斷），慢的四小時（全新的壞法，得從頭摸索）。

有了 triage agent 之後，五次事故的中位數是十八分鐘。區間是十二到二十八。二十八分鐘那個離群值是第三次事故，agent 判斷錯誤，我們在錯誤線索上浪費了時間。

我更在意的數字：活躍事故期間發出的利害關係人更新數。之前：中位數一則，通常是在修復已經在進行時才發出。之後：中位數四則，第一則在警報後十分鐘內就發出。這才是真正被打通的環節。Triage agent 不只加速了診斷——它把人類從 query engine 的角色裡釋放出來，去做人類真正擅長的事：讓等答案的人不再乾等。

工程師本來就該做的事

算事故成本，大家習慣盯停機分鐘數。那當然重要。但真正吃人的隱性成本——而且會逐季複利的——是知識壟斷。每一次只有一個人能做 triage 的事故，都讓那個人更不可或缺，讓團隊更脆弱。資深工程師變成 SPOF（單點故障），不是他們自願的——事故應變天生就是師徒制，永遠不會有夠多的事故讓每個人都練到，而真正發生的那些又太急，根本沒餘裕拿來教學。

Triage agent 沒有取代我。它揭露了我一直以來本該在做什麼。

這些年做事故應變，我以為自己的價值就是診斷問題。當那個 query 記得最多、metric 看得最懂、系統壞法最熟的人——或者至少在真正熟的人不在時，能頂著上場撐住。大家也是這樣期待我的。但診斷問題從來不是團隊的難處——它之所以難，只是因為知識被鎖在一個人的腦袋裡，而那個人不一定在場。真正的難處，那個影響客戶、利害關係人和業務的部分，是在壓力下清楚溝通、跨團隊協調、以及對嚴重性和緩解取捨做判斷。我沒有在做這些，因為我正忙著當人肉 query engine。

Agent 接手了 query engine 的活。剩下的，才是真正重要的工作：跟人講話、拍板、帶人。回頭看，所謂的「英雄工程師」一點都不英雄。不過是一個碰巧更有經驗，或者打字比較快的瓶頸。

我不知道第六次事故會教 skill 什麼。那正是重點——它不需要在第一天就完整，只需要每次事故之後比上次更強。而團隊需要信任它到願意用、又懷疑它到願意改。到目前為止，這兩條線都不難守住。

我帶 Ubiquiti 的 SSO 團隊。我們負責認證、token 管理、使用者 provisioning——那種每個團隊都依賴但沒人想到的基礎設施，直到它壞掉。這是一份沒人感謝但出了事一定被抓出來的工作。

幾週前我們在 email module 裡發現了瓶頸。每個碰到 email 的 API——密碼重設、MFA 驗證、邀請流程、通知偏好——都比應有的速度慢。修法很直接：把 email module 每次呼叫都重新初始化的關鍵元件做 cache。Template rendering、SMTP 連線 metadata、收件人驗證結果。那些在 request 之間不會變但每次都從頭建立的東西，就像一個每天清 node_modules 以求心靈淨化的工程師一樣。

我們對 caching layer 的正確性有信心。Unit test 過了。Integration test 也過了。問題是：真實流量打上去會怎樣？每個 import email module 的 API 應該都會變快。「應該」大概是工程師詞彙表裡最危險的兩個字。

是時候監控這次 rollout 了。

舊的做法，或：為什麼我花了兩天建一個沒人看的 Dashboard

這事我做過很多次了，劇本永遠一樣。

首先，你坐下來列舉每一個可能受影響的 API。你打開 codebase，grep email module 的 import，建一份清單。你漏了兩個，因為它們走的是一個不直接 import module 的內部 wrapper。你之後會發現這件事，在最糟糕的時機。

然後你寫一個 script。或者你建一個 CloudWatch dashboard。或者兩個都做——因為 script 給你原始數據，dashboard 給你漂亮的圖表，好在有人在 incident channel 問「一切都還好嗎？」的時候回覆一些比「ok」更有說服力的東西。

Dashboard 上有每個 API 的 status code 分布、p50 和 p95 latency、request volume 的面板。你把它們排列整齊。你設定合理的 Y 軸範圍。你暫時覺得自己很能幹。

你部署了。

第一個小時看起來不錯。Latency 全面下降。你在 team channel 發了一張截圖和一個低調的慶祝 emoji。然後有人回報那個 legacy user-export endpoint——兩個季度前就 deprecated 了但三個企業客戶還在呼叫因為沒人強制執行 deprecation 的那個——開始回 500。原來 caching layer 跟一段會把 mutable config object 傳進 email module 然後期待 module 修改它作為 side effect 的 code path 互動不良。那種你永遠不會刻意設計但在任何超過十八個月的 codebase 裡自然長出來的東西。

現在你進入 incident 模式。你需要一個不在 dashboard 上的 API 的數據。你 SSH 進一台機器。你對 metrics store 跑 ad-hoc query。你用 grep 的輸出和善意建構一個 mental model。你找到 bug，推一個修復，驗證修復，然後開始文書作業：incident report、deprecated endpoint migration 的 Jira ticket、一個 post-mortem action item 寫著「改善監控覆蓋率」。你還需要更新 dashboard 把你漏掉的 API 加進去，因為下一次——永遠有下一次——你想看到完整的畫面。

監控本來應該幫你度過 release 的。結果它變成了自己的專案，有自己的 bug、自己的維護負擔、自己的技術債。你建的 dashboard 截至今天是正確的。到了下一季，當有人新增一個依賴 email 的 endpoint，它又會不完整，而且沒人會更新它，因為沒人會更新 dashboard。它們是基礎設施的技術債：短命、繁殖力強、第一天之後基本上就被忽略了。

這個循環我經歷了十幾次。我以為事情就是這樣運作的。營運的代價。跟加班和 on-call 一樣，是工程師逃不掉的宿命。

新的做法，或：跟你的監控聊天

這次我做了不一樣的事。我沒有寫 script 或建 dashboard，而是請 Claude Code 幫我建一個 skill。

Skill 在 Claude Code 裡是一個可重複使用的 command——一組指令和 tool 定義的集合，agent 可以執行它。把它想成一個會思考的 script。Bash script 遵循一個固定的指令序列，當現實偏離作者的假設時就崩潰；skill 給 agent 一個目標，讓它自己想辦法達成。

大致上我是這樣要求的：「建一個 post-release 監控 skill。它應該 spawn 兩個並行的 agent——一個看 service 層級的 metrics，像是每個 API endpoint 的 status code 和 latency；一個看基礎設施層級的 metrics，像是 CPU、記憶體和 connection pool 使用率。我要能告訴它監控多久、聚焦哪個服務。」

就這樣。不用手動列舉 API。不用設計 dashboard layout。不用寫 CloudWatch metric query。Skill 理解監控目標，知道怎麼查詢我們的 metrics 系統，而且是透過觀察實際流量數據來找出哪些 endpoint 存在，而不是靠我那不完整的 codebase mental model。

我們寫了一個 command：/monitor-release --service email --duration 2h。Agent 啟動，分叉成兩個監控執行緒，開始觀察。它在終端機給我即時摘要。Service agent 回報每個 endpoint 的 latency 變化和百分比改善。Infra agent 回報資源使用率趨勢。兩個都會標記異常。

我部署了 caching layer。Skill 開始工作。Latency 下降了。摘要看起來很乾淨。我把截圖發到 team channel。

然後那個 legacy user-export endpoint 開始噴 500。跟舊世界裡會碰到的一樣的 bug。一樣不在我雷達上的 deprecated API。

但這次，監控 agent 注意到了。它不受限於我 hardcode 在 dashboard 裡的預定義 endpoint 清單。它觀察的是 email service 的實際流量模式，當一個原本回 200 的 endpoint 突然開始回 500，它標記了。我不用 SSH 進任何機器。我不用寫 ad-hoc query。Agent 告訴我：「/v1/users/export endpoint 從 14:32 UTC 開始出現 500 status code 激增。這個 endpoint 不在初始監控範圍內，但它透過 UserBulkOperations 間接 import 了 email module。要我加進主要觀察清單嗎？」

要。當然要。

當你可以直接說出你想要什麼

舊的做法和新的做法在這裡分歧大到叫它「改進」都太保守了。這是不同的生命週期。

舊世界裡，發現你需要監控一個新 endpoint 意味著：到 CloudWatch，建一個新 widget，設定 metric query，選 statistic，設 period，調整 dashboard layout，儲存，回去處理你本來在調查的問題。最少十分鐘，前提是你很熟 CloudWatch。二十分鐘如果你需要查 metric namespace。

新世界裡：「把 /v1/users/export 加到觀察清單。」搞定。Agent 已經在監控了。花費時間：四秒鐘加上打一句話需要的卡路里。

但更好的還在後面。初始監控期之後，我意識到我需要更細緻的 latency 數據。預設是 p50 和 p95。對 caching 變更來說，我想看 p99——因為 cache miss 不成比例地影響 tail latency。我也想看最小值，因為可疑的低最小值可能代表某個 endpoint 在到達 email module 之前就 short-circuit 了。我還想看 p99 排除 outlier，因為我們有一些企業客戶的 request 因為資料量大所以合理地比較慢，它們會 skew tail。

舊世界：每個 endpoint 三個新的 CloudWatch math expression。一種 metric query 語言，讀起來像有人在收訊很差的電話裡跟一個 Perl 愛好者描述 SQL。最少三十分鐘。

新世界：「也給我看 p99、min、和排除 response time 前 1% 的 p99。」Agent 更新了自己的報告。下次刷新，新的欄位就在那了。

然後這是讓我到現在還驚訝的部分，即使已經這樣工作了好幾週：我叫 agent 更新 skill 本身。不只是當前的監控 session——而是 skill 的定義。「更新 skill，讓 p99、min 和 p99-excluding-outliers 預設就包含在未來的執行中。」Agent 修改了自己的指令。下次我團隊的任何人跑 /monitor-release，那些統計數據從一開始就在那裡。沒人需要去要求。沒人需要知道我曾經花了一個下午才發現它們很重要。Skill 吸收了這個教訓。

會自我學習的Skill

這是我一直在想的洞察：skill 不是用完就丟的東西。它是一個累積營運智慧的產出物。

一個監控 script，一旦寫完，就凍結了。它反映的是一個工程師在某個時間點的理解。當你在 release 過程中學到東西——這個 endpoint 重要、那個 metric 是雜訊、這個 threshold 太敏感——你可以更新 script，但老實說大部分人不會。他們在心裡記一下，下次手動處理，最終離開公司，帶走那些知識。Script 繼續凍結著。某個新人跑了它，拿到不完整的數據，循環重來。

Skill 有不同的生命週期。每次你使用它，你都可以教它。「嘿，也觀察 connection pool exhaustion——上次被這個咬到。」Agent 更新 skill。「部署期間 /v1/health 的 404 spike 可以忽略，那是預期的。」Agent 加入例外。Skill 變成團隊對於 release 期間什麼重要的集體記憶，編碼在一種既人類可讀又機器可執行的格式裡。

我們的 rollout 結束時——caching layer 驗證完成、bug 修復、deprecated endpoint 打了 patch、incident report 寫完——我把 skill commit 進 repository。它是一個 Markdown 檔案加上 tool 定義和監控指令。新工程師可以讀它，理解團隊在 performance release 期間監控什麼以及為什麼。他們也可以直接跑它，開箱即用地拿到監控，不用理解裡面每一個決策。

跟舊世界比一下。Release 結束後你有的是：一個已經半過期的 CloudWatch dashboard、一個只在你機器上能跑的 bash script、一份在 Confluence 裡沒人會讀的 incident report、還有散布在 Slack thread 裡的部落知識。新工程師加入，問「我們怎麼監控 release？」然後得到一個聳肩和一個兩季之前的 dashboard 連結。

現在他們拿到一個 skill。他們跑它。它能用。當他們在自己的 release 中學到新東西，他們教給 skill，下一個人就受益。

我現在真正相信的

我想在這裡謹慎一點，因為我在這個產業待得夠久，知道「現在一切都不同了」幾乎永遠是錯的，而那少數幾次它是對的，對的方式也是沒人預料到的。

AI skill 沒有取代監控。我還是有 CloudWatch。還是有 Grafana。Metrics 管線沒有變。變的是我和我的監控之間的介面——以及我在使用過程中累積的營運知識的生命週期。

這件事的影響超乎想像地大。

傳統的開發生命週期有這些離散的、痛苦的交接：你做計畫、建監控、部署、發現監控不完整、修監控、發現問題、修問題、再次更新監控、寫 incident report、開 ticket，然後你繼續前進，監控開始腐爛。每個階段是獨立的活動，有自己的工具和自己的摩擦。

Skill 把這一切壓縮成一個連續的對話。Release 前，你描述你想觀察什麼。Release 期間，你用說的即時調整。Release 後，你 commit skill，調整被保留下來。監控、incident 調查、知識捕獲——現在它們是同一個活動。你不用在「監控」和「incident response」和「文件撰寫」之間切換 context。你只是持續跟 agent 對話，skill 吸收一切。

這是典範轉移嗎？我不確定我在意那個標籤。我知道的是，這次 release 我花了大約兩小時在監控上，上一次沒有 skill 的同等規模 release，我花了將近兩天。我知道監控覆蓋率更好——skill 抓到了一個我會漏掉的 endpoint。我知道我 commit 的那個產出物對我的團隊比我建過的任何 dashboard 都有用。而且我知道下一次，skill 會比這次更好，因為它從這次 release 學到了東西，下一次它也會繼續學。

最好的工具是那些越用越聰明的工具。我的監控設定，職涯中第一次，符合這個標準。

不過 CloudWatch dashboard 我還是會留著。舊習難改，需要把累積重要的數據還是放上去，而且總得有人截圖給 incident channel 看。有些典範會轉移。有些只是多了一個更好的副駕駛。

I lead the SSO team at Ubiquiti. We handle authentication, token management, user provisioning — the kind of infrastructure that every other team depends on and nobody thinks about until it breaks. It is a thankless gig with excellent job security.

A few weeks ago we identified a bottleneck in our email module. Every API that touches email — password resets, MFA verification, invite flows, notification preferences — was slower than it should have been. The fix was straightforward: cache the critical components that the email module initializes on every call.

We were confident the caching layer was correct. Unit tests passed. Integration tests passed. The question was: what happens when we flip this on for real traffic? Every API that imports the email module should get faster. "Should" is the word that has ruined more weekends than any other in the English language.

Time to monitor the rollout.

The Old Way, or: How I Learned to Stop Worrying and Build Dashboards That Nobody Reads

I have done this dance before. Many times. The steps are always the same.

First, you sit down and enumerate every API that could be affected. You open the codebase, grep for email module imports, build a list. You miss two because they go through an internal wrapper that doesn't import the module directly. You will discover this later, at the worst possible time. You don't blame yourself because people left this legacy 10 years ago, but other people sure do blame you when things go south.

Then you write a script. Or you build a CloudWatch dashboard. Or both, because the script gives you the raw data and the dashboard gives you the pretty graphs for the incident channel when someone asks "is everything okay?" and you need to respond with something more convincing than "I think so."

The dashboard has panels for each API's status code distribution, p50 and p95 latency, and request volume. You arrange them neatly. You set reasonable Y-axis ranges. You feel briefly competent.

You deploy.

The first hour looks good. Latencies are down across the board. You send a message to the team channel with a screenshot and a modest celebration emoji. Then someone reports that the legacy user-export endpoint — the one that was deprecated two quarters ago but that three enterprise customers still call because nobody enforced the deprecation — is returning 500s. It turns out the caching layer interacts badly with a code path that passes a mutable config object into the email module and expects the module to modify it as a side effect. The kind of thing you would never design on purpose but that accretes naturally in any codebase older than eighteen months.

Now you are in incident mode. You need data on an API that is not in your dashboard. You SSH into a box. You run ad-hoc queries against the metrics store. You build a mental model from grep output and good intentions. You find the bug, push a fix, verify the fix, and then start the paperwork: incident report, Jira tickets for the deprecated endpoint migration, a post-mortem action item to "improve monitoring coverage." You also need to update your dashboard to include the APIs you missed, because next time — and there is always a next time — you want to see the full picture.

The monitoring was supposed to help you through the release. Instead it became its own project, with its own bugs, its own maintenance burden, and its own technical debt. The dashboard you built is correct as of today. By next quarter, when someone adds a new email-dependent endpoint, it will be incomplete again, and nobody will update it, because nobody ever updates dashboards. They are the fruit flies of infrastructure: brief, prolific, and largely ignored after the first day.

I have lived this cycle a dozen times. I assumed it was just how things worked. The cost of doing business. The developer's version of death and taxes.

The New Way, or: Talking to Your Monitoring

This time I did something different. Instead of writing a script or building a dashboard, I asked Claude Code to build me a skill.

A skill, in Claude Code, is a reusable command — a bundle of instructions and tool definitions that an agent can execute. Think of it as a script that can think. Where a bash script follows a fixed sequence of commands and crashes when reality deviates from the author's assumptions, a skill gives the agent a goal and lets it figure out how to get there.

Here is what I asked for, roughly: "Build a post-release monitoring skill. It should spawn two concurrent agents — one watching service-level metrics like status codes and latency for each API endpoint, and one watching infrastructure-level metrics like CPU, memory, and connection pool utilization. I want to be able to tell it how long to monitor and which service to focus on."

That was it. No enumerating APIs by hand. No designing dashboard layouts. No writing CloudWatch metric queries. The skill understands the monitoring goal, knows how to query our metrics systems, and figures out which endpoints exist by looking at the actual traffic data rather than my incomplete mental model of the codebase.

We wrote a command: /monitor-release --service email --duration 2h. The agent spins up, forks into the two monitoring threads, and starts watching. It gives me a running summary in the terminal. Service agent reports latency changes per endpoint with percentage improvements. Infra agent reports resource utilization trends. Both flag anomalies.

I deployed the caching layer. The skill started doing its job. Latencies dropped. The summary looked clean. I sent the screenshot to the team channel.

Then the legacy user-export endpoint started throwing 500s. Same bug as I would have hit in the old world. Same deprecated API that was not on my radar.

But this time, the monitoring agent noticed. It was not limited to a predefined list of endpoints I had hardcoded into a dashboard. It was watching the actual traffic patterns for the email service, and when an endpoint that had been returning 200s suddenly started returning 500s, it flagged it. I did not have to SSH into anything. I did not have to write an ad-hoc query. The agent told me: "The /v1/users/export endpoint is showing a spike in 500 status codes starting at 14:32 UTC. This endpoint was not in the initial monitoring scope but it imports the email module transitively through UserBulkOperations. Want me to add it to the primary watch list?"

Yes. Yes I do.

When You Can Just Ask for What You Want

Here is where the old way and the new way diverge so completely that calling it an "improvement" undersells it. It is a different lifecycle.

In the old world, realizing you need to monitor a new endpoint means: go to CloudWatch, create a new widget, configure the metric query, choose the statistic, set the period, adjust the dashboard layout, save, go back to actually fixing the problem you were investigating. Minimum ten minutes if you know CloudWatch well. Twenty if you need to look up the metric namespace.

In the new world: "Add /v1/users/export to the watch list." Done. The agent is already monitoring it. Time spent: four seconds and the calories required to type one sentence.

But it got better. After the initial monitoring period, I realized I wanted more nuanced latency data. The default was p50 and p95. For a caching change, I wanted to see p99 — because cache misses affect tail latency disproportionately. I also wanted to see the minimum, because a suspiciously low minimum might indicate an endpoint short-circuiting before it reaches the email module. And I wanted p99 excluding outliers, because we have a handful of enterprise customers whose requests legitimately take longer due to data volume, and they skew the tail.

Old world: three new CloudWatch math expressions per endpoint. A metric query language that reads like someone described SQL to a Perl enthusiast over a bad phone connection. Thirty minutes of work, minimum.

New world: "Also show me p99, min, and p99 excluding the top 1% by response time." The agent updated its own reporting. Next refresh, the new columns were there.

And here is the part that still surprises me, even after weeks of working this way: I told the agent to update the skill itself. Not just the current monitoring session — the skill definition. "Update the skill so that p99, min, and p99-excluding-outliers are included by default for future runs." The agent modified its own instructions. The next time anyone on my team runs /monitor-release, those statistics are there from the start. Nobody needs to ask for them. Nobody needs to know that I once spent an afternoon discovering they were important. The skill absorbed the lesson.

The Artifact That Learns

This is the insight that I keep coming back to: the skill is not a throwaway. It is an artifact that accumulates operational wisdom.

A monitoring script, once written, is frozen. It reflects the understanding of one engineer at one point in time. When you learn something during a release — this endpoint matters, that metric is noise, this threshold is too sensitive — you can update the script, but honestly, most people do not. They make a mental note, handle it manually next time, and eventually leave the company, taking the knowledge with them. The script stays frozen. Some new person runs it, gets incomplete data, and the cycle repeats.

The skill has a different lifecycle. Every time you use it, you can teach it. "Hey, also watch for connection pool exhaustion — that bit us last time." The agent updates the skill. "Ignore 404 spikes on /v1/health during deployments, those are expected." The agent adds the exception. The skill becomes the team's collective memory of what matters during a release, encoded in a format that is both human-readable and machine-executable.

When our rollout was done — caching layer verified, bug fixed, deprecated endpoint patched, incident report filed — I committed the skill to the repository. It is a Markdown file with tool definitions and monitoring instructions. A new engineer can read it and understand what the team watches during a performance release and why. They can also just run it and get the monitoring out of the box, without understanding every decision baked into it.

Compare this to the old world. After a release, you have: a CloudWatch dashboard that is already half-stale, a bash script that works on your machine, an incident report in Confluence that nobody will read, and tribal knowledge distributed across Slack threads. The new engineer joins, asks "how do we monitor releases?" and gets a shrug and a link to a dashboard from two quarters ago.

Now they get a skill. They run it. It works. And when they learn something new during their own release, they teach it to the skill, and the next person benefits.

What I Actually Believe Now

I want to be careful here because I have been in this industry long enough to know that "everything is different now" is almost always wrong, and the few times it is right, it is right in ways nobody predicted.

The AI skill did not replace monitoring. I still have CloudWatch. I still have Grafana. The metrics pipeline did not change. What changed is the interface between me and my monitoring — and the lifecycle of the operational knowledge I accumulate while using it.

That turns out to matter enormously.

The traditional development lifecycle has these discrete, painful handoffs: you plan, you build the monitoring, you deploy, you discover the monitoring is incomplete, you fix the monitoring, you discover problems, you fix the problems, you update the monitoring again, you write the incident report, you file the tickets, and then you move on and the monitoring rots. Every phase is a separate activity with its own tools and its own friction.

The skill collapses all of that into a continuous conversation. Pre-release, you describe what you want to watch. During the release, you adjust in real time by talking. Post-release, you commit the skill and the adjustments are preserved. The monitoring, the incident investigation, the knowledge capture — they are the same activity now. You do not context-switch between "monitoring" and "incident response" and "documentation." You just keep talking to the agent, and the skill absorbs everything.

Is this a paradigm shift? I am not sure I care about the label. What I know is that I spent roughly two hours on monitoring for this release, and in my previous comparable release without the skill, I spent closer to two days. I know that the monitoring coverage was better — the skill caught an endpoint I would have missed. I know that the artifact I committed is more useful to my team than any dashboard I have ever built. And I know that next time, the skill will be better than it was this time, because it learned from this release, and it will learn from the next one too.

The best tools are the ones that get smarter as you use them. For the first time in my career, my monitoring setup qualifies.

I am still going to keep the CloudWatch dashboards, though. We'll be accumulating the really critical metrics there, and someone needs something to screenshot for the incident channel. Some paradigms shift. Some just get a better co-pilot.

在人工智慧的熱潮中，「AI Agent（代理人）」被描繪成無所不能的數位管家。但在我們這些實際部署系統的工程師眼中，Agent 並不是魔法，而是一種精密的系統架構。

原始詳細調查跟學習筆記在此：https://schwannden.github.io/ai-agent-study/zh-tw/

核心解構：Workflow vs. Agent

在深入設計模式之前，我們必須先釐清 Anthropic 提出的一個關鍵區別：你是需要一個 Workflow（工作流），還是一個 Agent（代理人）？

1. Workflows（工作流）：確定性的路徑

這是將 LLM 與工具透過預定義的程式碼路徑（Predefined Code Paths） 串接起來的系統。

• 特點：路徑是固定的，LLM 僅負責執行節點內的任務（如摘要、分類）。

• 優點：高度可預測（Predictability）、一致性高。Anthropic 強烈建議從這裡開始。

• 適用場景：資料清洗、翻譯流水線、內容分類。

2. Agents（代理人）：動態的決策

這是讓 LLM 動態控制（Dynamically Direct） 流程與工具使用的系統。

• 特點：LLM 自行決定下一步該做什麼，甚至決定何時停止。

• 優點：靈活性極高，能處理開放式問題。

• 代價：延遲高、成本高、且容易出現錯誤累積（Compounding Errors）。

工程黃金法則：LLM 負責 「決策與推論（Reasoning）」，而 Agent 架構負責 「邊界控制與執行（Control & Execution）」。

三種架構模式：從敏捷到嚴謹

根據 Schwannden 的 AI 研究筆記 以及 Anthropic 的設計模式，我們可以將常見的架構歸納為以下三種。這不僅是風格的選擇，更是成本、延遲與準確度的權衡。

1. The Dynamic Looper（動態迴圈）：ReAct 模式

對應 Anthropic 概念：Autonomous Agent

這是最直觀、最敏捷的模式，也是典型的「Agent」。

• 運作機制：思考（Reason）→ 行動（Act）→ 觀察（Observe）。LLM 根據當下情況動態決定下一步，形成一個即時的反饋迴圈。

• 工程視角：這是一個單執行緒的狀態機。

• 優點：極高的靈活性，能處理未知的動態問題。適合 MVP（最小可行性產品）。

• 缺點：錯誤累積（Error Propagation）風險高。Anthropic 警告，這種自主性在缺乏護欄的情況下，容易讓模型在錯誤的路徑上越走越遠。

📚 技術深讀：ReAct 模式概覽實作參考：Claude ReAct Implementation

2. The Systematic Pipeline（系統化流水線）：Plan-Execute-Verify 模式

對應 Anthropic 概念：Orchestrator-Workers & Evaluator-Optimizer

當任務容錯率低（如法律審查、金融操作）時，我們不能依賴 LLM 的即興發揮。我們需要將流程結構化為 Workflow。

• 運作機制：這是關注點分離的極致體現，Anthropic 將其細分為兩種強大的子模式：

  1. Orchestrator-Workers（指揮家-工人）：一個中央 LLM（Planner）將任務拆解，分發給多個 Worker LLM（Executor）平行處理。適合複雜的編碼或資料蒐集任務。

  2. Evaluator-Optimizer（評估者-優化者）：一個 LLM 生成內容，另一個 LLM（Verifier）負責評估並提供反饋，形成優化迴圈。

• 工程視角：這類似於 Map-Reduce 模型。它犧牲了延遲與 Token 成本，換取了輸出的可預測性與可靠性。

📚 技術深讀：PEV 架構概覽實作參考：Claude Planning Implementation

3. The Collaborative Guardrail（協作護欄）：Human-in-the-Loop 模式

對應 Anthropic 概念：Human-in-the-Loop Workflow

在某些高風險場景，AI 不應是全自動的黑盒子。

• 運作機制：系統在關鍵決策點（Critical Junctions）會「掛起（Suspend）」執行狀態，請求人類介入。Anthropic 特別強調在 Coding Agents 或客戶支援場景中，這種模式是確保安全與合規的關鍵。

• 關鍵技術：這考驗後端架構的 「持久化狀態管理（Persistent State）」。

• 哲學：這是**安全與合規（Safety & Compliance）**的最終防線。

📚 技術深讀：人機協作概覽實作參考：Human-in-the-Loop Implementation

架構決策指南：Anthropic 的建議

身為技術決策者，該如何選擇架構？Anthropic 給出了非常務實的建議：從簡單開始（Start Simple）。

1. 優先考慮 Workflow (Prompt Chaining / Routing)

   • 如果任務可以被拆解為固定的步驟（例如：先寫大綱，再寫文章），請使用 Workflow。不要為了用 Agent 而用 Agent。

   • 這樣可以獲得更低的延遲和更高的可靠性。

2. 何時升級為 Agent？

   • 當問題是開放式的（Open-ended），且你無法預測需要多少步驟才能解決時（例如：「幫我修復這個程式碼庫中的 Bug」）。

   • 這時你需要 ReAct 模式的靈活性，但請務必加上 Sandbox 環境進行測試。

3. 追求品質的終極手段：Evaluator-Optimizer

   • 如果你發現單次生成的品質不夠好，加入一個「評估者」步驟往往比不斷調整 Prompt 更有效。這就是 PEV 模式的核心價值。

結語：在混沌中建立秩序

構建 AI Agent 的藝術，在於用確定性的程式碼去駕馭機率性的模型。

LLM 是一個強大但充滿不確定性的引擎。一個好的架構師，懂得在 Anthropic 提倡的 Workflows 與 Agents 之間靈活切換——在需要穩定的地方建立流水線，在需要創意的地方釋放代理人。

下一次當你設計系統時，請記得：Complexity is a cost（複雜度是一種成本）。 只有在簡單的 Workflow 無法滿足需求時，才引入自主的 Agent。

參考資源：

• Anthropic: Building Effective Agents

• Schwannden's AI Agent Study

或許是因為在大型語言模型的強化學習 (RL) 或微調過程中，設計者主要將模型的優化目標聚焦於事實準確性、邏輯連貫性與安全合規上。然而，人類靈魂深層的、非結構性的、詩意的需求，卻很少成為 AI 被深度優化的目標。

幸好，人類歷史上有無數偉大的屬靈導師，他們的作品早已沉澱了千年智慧。既然 AI 缺乏深沉的靈魂維度，我們何不將這些屬靈經典作為 AI 的「記憶」？我決定做一個實驗：透過 RAG (Retrieval-Augmented Generation) 技術，將畢德生(Eugene Peterson) 的牧者智慧和坎培斯 (Thomas à Kempis) 的修院語氣等人的著作注入 AI 的知識庫。

以下就是我一步步用「提示（prompt）」打造我的心靈導師的過程。

從 PDF 到章節：讓經典被「讀懂」

我的第一個挑戰是讓這些經典「讀得懂」。這些智慧都被鎖在一整份龐大的 PDF 檔案裡。我想要的不是把整本書隨機切成幾百個碎片（那會失去語境，像完整的故事被斷章取義），而是要尊重作者，按「章節」來理解。畢竟，一個章節本身就是一個完整的思緒單元。

我寫了幾個prompt，幫我把 PDF 檔案逐章逐節地轉換成 Markdown，並要求它務必保留原文的語氣，一個字都不許亂改。拿到初稿後，我又讓 AI 幫我按章切分檔案，確保每一個檔案都是一個獨立的、帶有語義完整性的「記憶」單元。這是 RAG 系統穩定的基礎。

建立心靈圖書館：Chroma 與索引卡

接下來，我需要一個「圖書館」來存放這些珍貴的章節。我選擇了 Chroma 雲端服務，主要是看中它的免費額度與免維護特性（不用自己維護database）。

我又請 AI 幫我生成了一個簡單的 Python 腳本。這個腳本走訪每個章節檔案，並在寫入 Chroma collection 時，一併附上「書名」和「章名」這兩個關鍵的「標籤」（Metadata）。這就像給每一段智慧語錄都貼上了一張清晰的索引卡，確保未來檢索時能精確找到出處。

給 AI 戴上導師的帽子

參考指令

Build a FastAPI RAG chatbot that serves a small Tailwind frontend at /chat. Use Python 3.11, FastAPI, httpx, ChromaDB (cloud client) for embeddings retrieval, and LM

Studio’s OpenAI-compatible local API for generation. Requirements:

• Env vars: CHROMA_API_KEY, CHROMA_TENANT, CHROMA_DATABASE (default “dev”), LM_STUDIO_BASE_URL (default http://host.docker.internal:1234), LM_STUDIO_CHAT_MODEL (default openai/gpt-oss-20b).

• Retrieval: top_k with default 7, cap 8; allocate fairly across collections. Max context per doc 1200 chars. Response length presets: short/medium/long with approximate char targets.

• Chat endpoint POST /chat: accepts messages [{role, content}], top_k, collections, response_length; returns reply plus sources (collection, label, filename, distance).

現在，我的「圖書館」有了，就需要一位「館長」來處理請求。我再次使用提示，請 AI 幫我搭建一個 FastAPI 伺服器作為後端。這位「館長」的任務很明確：

1. 根據使用者選擇的導師，到圖書館裡檢索出最相似的幾段經文。

2. 把這些經文優雅地彙整成一個「上下文」。

3. 最關鍵的是：它必須在這個上下文中，要求回應模型使用「屬靈導師的口吻」，溫柔、沉穩，並明確標註來源章節。

4. 最後一條戒律：如果圖書館裡找不到相關內容，它絕對不能亂編，必須坦誠告知。

我就是在 AI 給出的骨架上，補足了錯誤處理和細節配置，讓它能順利將檢索到的智慧，送往我的本機推理模型進行「解讀」。

本機模型

我把語言模型跑在我自己的 Mac 上，搭配 LM Studio 與 MLX FP4 量化模型。

前端：

為了簡單的自己實驗整個Rag建置，我沒有使用既有的聊天框架，想看看 Codex 能不能理解我的概念，幫我兜出整個前端。看起來完全難不倒 Codex: https://github.com/schwannden/spiritual-director-chat

實驗：人格分離，讓導師的聲音更純淨

玩了一陣子後，我發現自己貪心了。我不想只有一位導師，我想能自由切換「畢德生的牧者語氣」和「坎培斯的修院語氣」，讓我可以看看中世紀的智慧跟當代牧者的差異。

於是我回頭修改提示，加入了「人格 (Persona) 分離」的設計。我讓前端增加了一個下拉選單，後端則會根據我的選擇，只去查對應的資料庫，或是將兩本書的上下文合併。更精確的系統提示，確保模型在回應時能保持選定導師獨有的語氣，避免兩位聖賢的聲音「混音」，讓指引更為純淨清晰。

參考指令

Evolve the existing RAG chatbot to support two distinct personas tied to the collections. Requirements:

• Collections stay “on-living-well” and “imitatio-christi”, but add persona-aware voices.

• on-living-well → Eugene Peterson: warm, pastoral, conversational.

• imitatio-christi → Thomas à Kempis: reflective, devotional, humble.

• both → blend the two voices naturally.

• Update the system prompt generation so the tone changes based on selected collections; keep the default to on-living-well when none provided.

• Keep retrieval/top_k logic intact; if “both” is requested, spread top_k across collections as before.

拿同一個問題，選擇不同的屬靈經典作為依據回答，AI確實可以開始模仿我們要他成為的人。

在這個小小的實驗室裡，我看到了不同世代屬靈智慧的差異：

• 當我選中畢德生的近代屬靈智慧時，導師的回應帶著一種溫柔的基調，教我們溫柔地對待自己，看重平凡與日常中的恩典。

• 當我切換到坎培斯的中世紀修院智慧時，回應則轉為一種更嚴謹、更克制的語氣，提醒我們要忘我、要捨己，將目光專注於更高遠的目標。

最終的反思：有限的科技，無限的生命

這個 RAG 實驗雖然成功地讓 AI 穿上了「屬靈導師」的外衣，但它也讓我更清楚地意識到：AI 在心靈領域能提供的幫助，終究是極其有限的。說到底，這次的嘗試，本質上只是想看看 AI 能否至少精確地模仿我喜歡的作者語氣，同時順便測試一些好用且免費的開源工具（如 Chroma、LM Studio）。

真正的屬靈指引，其困難度遠超於此。它沒有固定的 SOP 或一套通用的語氣。面對同一個問題，一位屬靈導師必須深知對方的光景與時代盲點，才能準確回應：究竟是該挑戰、安慰、責備，還是僅僅是單純地陪伴、禱告與聆聽？這一切，都需要建立在愛的關係、順服的關係、長時間累積的理解，以及在關係中不斷加深的認識。

因此，這個系統的最佳定位，是作為一本經典導讀工具，而非一位真正的導師。它為我們打開了一扇門，讓我們更貼近那些偉大靈魂的文字，但通往心靈深處的道路，依舊需要我們自己投入真實的生命與關係。

I wanted a Claude Code–style coding buddy that runs 100% locally on my MacBook Pro: no API keys, no cloud costs, and fast on Apple Silicon. After a short detour with MLX Knife, the winning combo was:

• LM Studio for a local, OpenAI-compatible API server

• GPT-OSS-20B (MXFP4) as the model

• OpenCode as the terminal coding agent

Below is exactly what I ran and clicked, plus the one config file that makes it all gel.

tl;dr (copy-paste)

# 1) Install LM Studio (GUI + local API server)
brew install --cask lm-studio

# 2) (Optional) launch LM Studio from terminal
open -a “LM Studio”

# 👉 In LM Studio UI:
# - Start the Local Server (Runtimes → Developer) until it says:
#   Reachable at http://127.0.0.1:1234
# - Load the model: gpt-oss-20b (MLX / MXFP4)
# - Turn the Context Length slider way up (OpenCode uses long prompts)

# 3) Quick API smoke test (expects LM Studio at :1234)
curl http://127.0.0.1:1234/v1/models
curl -s -X POST “http://127.0.0.1:1234/v1/chat/completions” \
  -H “Content-Type: application/json” -H “Authorization: Bearer EMPTY” \
  -d ‘{
    “model”: “gpt-oss-20b”,
    “messages”: [{”role”:”user”,”content”:”Say hi in one sentence.”}]
  }’ | jq .

# 4) Install OpenCode (terminal coding agent)
brew install sst/tap/opencode

# 5) Create OpenCode config (provider → LM Studio, model → gpt-oss-20b)
mkdir -p ./.opencode
cat > ./.opencode/opencode.json <<’JSON’
{
  “$schema”: “https://opencode.ai/config.json”,
  “provider”: {
    “lmstudio”: {
      “npm”: “@ai-sdk/openai-compatible”,
      “name”: “LM Studio (local)”,
      “options”: {
        “baseURL”: “http://127.0.0.1:1234/v1”,
        “apiKey”: “EMPTY”
      },
      “models”: {
        “gpt-oss-20b”: { “name”: “gpt-oss-20b” }
      }
    }
  },
  “model”: “lmstudio/gpt-oss-20b”
}
JSON

# 6) Run it 🚀
opencode

The longer story

I set out to recreate the “talk to your editor” workflow, but fully local. I first tried MLX Knife to host an OpenAI-compatible server on http://127.0.0.1:8000/v1. It did spin up—and even had a tiny simple_chat.html—but OpenCode needed a few API behaviors the server didn’t fully cover. Specifically, I ran into OpenAI-compat mismatches (e.g., JSON field naming) and a missing embeddings endpoint, which some clients expect. Those gaps are tracked in the project’s issues, so it may work out of the box later; it just didn’t for my setup today. (GitHub)

So I pivoted to LM Studio, which exposes the familiar OpenAI-like endpoints (/v1/models, /v1/chat/completions, /v1/completions, /v1/embeddings) on a local server—by default reachable at http://127.0.0.1:1234/v1. That instantly clicked with OpenCode. (LM Studio)

step-by-step (with a couple of gotchas I hit)

1) install LM Studio

brew install --cask lm-studio
open -a “LM Studio”

2) start the local server + load the model

In LM Studio:

• Go to Runtimes → Developer and toggle the server to Running. You should see Reachable at

http://127.0.0.1:1234

• and a list of supported OpenAI-like endpoints. (LM Studio)

• Load gpt-oss-20b (your screenshots show the MLX format with MXFP4 quantization).

• Important: drag the Context Length slider way up (your pic showed support up to 131072). OpenCode sends longer task prompts than a normal chat; with a tiny context window, tools won’t run well.

3) smoke test the API

curl http://127.0.0.1:1234/v1/models

curl -s -X POST “http://127.0.0.1:1234/v1/chat/completions” \
  -H “Content-Type: application/json” -H “Authorization: Bearer EMPTY” \
  -d ‘{
    “model”: “gpt-oss-20b”,
    “messages”: [{”role”:”user”,”content”:”Quick smoke test.”}]
  }’ | jq .

LM Studio speaks OpenAI-compatible JSON on those endpoints, so this should stream back a response. (LM Studio)

4) install OpenCode

brew install sst/tap/opencode

(Official install paths—brew and script—are in their docs/readme.) (opencode.ai)

5) point OpenCode at LM Studio (one config file)

I used a provider pointing to LM Studio’s baseURL. The config below is exactly what I run:

{
  “$schema”: “https://opencode.ai/config.json”,
  “provider”: {
    “lmstudio”: {
      “npm”: “@ai-sdk/openai-compatible”,
      “name”: “LM Studio (local)”,
      “options”: { “baseURL”: “http://127.0.0.1:1234/v1” },
      “models”: { “gpt-oss-20b”: { “name”: “gpt-oss-20b” } }
    }
  },
  “model”: “lmstudio/gpt-oss-20b”
}

Docs show exactly this pattern for OpenAI-compatible providers (custom baseURL, map of models). (opencode.ai)

Then put it in ~/.opencode/opencode.json

Once OpenCode boots, I select the model and start giving it real dev work (“set up a Go REST handler + Makefile and explain each change”), and it runs entirely through LM Studio locally.

what it’s like in practice

With LM Studio + OpenCode, the workflow feels like Claude Code in my terminal—edits, diffs, planning, and “do-this-then-that” loops—entirely offline. On my MacBook Pro, GPT-OSS-20B (MXFP4) is a sweet spot: strong reasoning, reasonable VRAM/RAM footprint, and it keeps up with iterative coding.

Final Note

Here are the reasons why I choose the tech stack:

• reasoning capability
  GPT-OSS-20B is a mixture-of-experts (MoE) model. Even though it has 20B parameters in total, only a subset of experts activate per request. This design gives it strong reasoning skills without needing to run all 20B parameters at once.

• runtime memory efficiency
  Because MoE only “turns on” part of the model each step, the effective compute is closer to ~3–4B active parameters. That keeps memory usage low enough to run smoothly on a MacBook Pro instead of a datacenter GPU.

• mlx optimization
  The model comes in MLX format, which is Apple’s deep learning framework optimized for M-series chips. MLX takes advantage of Apple Silicon’s GPU and memory architecture, so inference runs faster and more efficiently compared to generic formats.

• quantization (MXFP4)
  The weights are stored in MXFP4, a 4-bit floating-point quantization scheme supported natively in MLX. This drastically reduces the model’s footprint on disk and in RAM, while still preserving reasoning quality. In practice, this means GPT-OSS-20B (MXFP4) fits comfortably in ~12 GB, perfect for laptop use.

I suppose LM Studio could easily be swapped for something else that support MLX optimization. And open code can be swapped for something like goose too. Try and play with your favorite tool! The horizon for edge AI is getting closer and closer.

references

• LM Studio OpenAI-like endpoints: /v1/models, /v1/chat/completions, /v1/completions, /v1/embeddings. (LM Studio)

• LM Studio via Homebrew cask (install line). (Homebrew Formulae)

• OpenCode providers/config (custom OpenAI-compatible baseURL). (opencode.ai)

• MLX Knife issues illustrating why I switched (format mismatch & missing embeddings). (GitHub)

網址：prayer.simtaiwan.org

一頓午餐完成的 PoC

那天午餐的時候，SIM 的 Roger 突然問我：「能不能找個時間聊聊？」
我心想反正我帶著電腦，就說：「不如現在就開始吧。」
他有點驚訝，本來以為要先交通想法、評估困難度，沒想到我們就直接開工了。

一小時以後，網站圓形大致完成。但是從看起來完成，到一個專業可維護的上線網站，中間還發生了什麼事呢？

從原型到正式上線

PoC 雖快，但要真正上線還有幾個關卡。

Github Pages 提升效能

Lovable 的痛點在於 loading 太慢。所以我把專案接上 Github，利用 Github Pages 來發佈，效能直接提升。Loading的時間從3秒鐘降到幾百毫秒。
但這裡有個坑：因為我們是 SPA（Single Page Application），直接放在 Github Pages 會遇到 routing 問題。

上傳到 Github Pages 的時候，會遇到一個特別的麻煩：SPA（Single Page Application）本身的路由，會被 Github Pages 的內建 routing 擋住。原因是這樣的：

• 在 React Router（或 Vue Router）裡，/prayer/123 其實只是由前端解讀的虛擬路由。

• 但 Github Pages 不是這樣想，它會真的去伺服器裡找 /prayer/123 這個資料夾或檔案。

• 找不到？那就直接回 404。

換句話說，Github Pages 的靜態檔案伺服器 router，會先攔截掉 request，導致 React Router 根本沒機會處理。

Workaround：Custom 404 Redirect

解法是我們自己做一個 客製化的 404 頁面：

1. 使用者打 /prayer/123 → Github Pages 找不到 → 跳到我們的 404.html。

2. 在 404.html 裡，我們把當前的 path、query parameter、hash 都記下來。

3. 接著用 JavaScript 把使用者導回 /（root）。

4. 這時候 React Router 接手，讀到剛剛傳過來的路由資訊，再判斷該顯示哪一個頁面。

自訂網域 & Cloudflare

接著，我們需要一個好記的網址。SIM 的 IT 幫忙在 DNS 加了 CNAME，指到 Github Pages。再透過 Cloudflare 設定 Custom Domain，就能用上 prayer.simtaiwan.org (請看Github官方教學)。

Supabase 帳號切換

由於我自己的 Supabase 免費額度已經爆掉，所以乾脆用 SIM 的 email 申請新的專案，再邀請我自己進去做管理員，方便長期維護。

工程品質：從 README 到 Release

穩定上線後，專案不只要能跑，更要「可維護」。

1. README / Contributing Guide
   我用 Cursor 和 Claude Code 幫忙生成文件，讓任何後續的同工可以快速上手。

2. CI/CD 品質控管
   設定了 linter、type check、prettier 等自動檢查，避免品質下滑。

3. Dependabot 自動更新
   套件沒有定期更新，是很多專案的主要死因...

4. 版本管理 Conventional Commit + Release Please

這個組合是我在自己的開源專案裡愛上的一套流程。

Conventional Commit 的規範，要求我們在 commit message 裡面加上簡單的前綴：

• feat: → 新功能

• fix: → 修 bug

• docs: → 文件更新

• chore: → 其他雜事
  …還有其他細分。

這樣一來，commit log 不再是「亂糟糟的備忘錄」，而是結構化的資訊。

接著，Release Please 就能讀懂這些規範化的 commit，幫我：

1. 自動產生 CHANGELOG（清楚列出新增、修正、變更）。

2. 自動 bump 版本號（依照 semver：feat 就升 minor，fix 就升 patch）。

3. 自動發 release（甚至能幫忙建 tag、打 package）。

結果就是：我根本不用自己盯著版本號，或擔心 changelog 忘了寫。
整個 release 流程只要點幾下即可完成，特別適合這種公開、要長期維護的專案。

產品思維：從需求翻譯開始

這段過程最有趣的，其實是「需求翻譯」。

Roger 一開始希望上傳兩張圖：一張中文，一張英文。但我建議直接用 i18n（國際化機制），同一張圖就能自動切換語言，不需要兩份檔案。一般使用者在把一個想法轉成網站的時候，會想像把它本來的流程原封不動變成網頁，但是作為設計師我們可以用我們對於網站如何被使用的專業，來協助。

很多使用者其實不知道還有什麼可能性。例如：字體調整，Dark Mode，PWA（安裝成 App）... 等等，這些都是讓手機版更好閱讀的工具。

另外，每一篇禱告到底要是一個popup還是一個獨立頁面？這就跟你有沒有想要讓使用者分享某一篇禱告，還是你只有想要讓使用者分享網頁。這些設計所帶來的使用者習慣區別，都可以溝通清楚～

以上通通只要在 Lovable 聊聊天就完成，完全不用寫 code。真正有價值的地方，就是釐清真實需求。

圖片壓縮：為 20 年後預先設想

另一個潛在問題，是 Supabase 免費空間只有 1G。禱告圖檔一張就好幾 MB，照這樣上傳，五年內就爆掉了。

我先想過請同工壓縮再上傳，但這樣太麻煩，也不現實。最後決定直接在前端用 compressor.js：每張圖在上傳前自動壓到 300kb 左右。這樣 1G 空間至少能撐 50 年，使用者也完全不用改變習慣。

回顧：Vibe Coding 的精髓

Vibe Coding 讓有些人覺得，好像以前那些程式能力都派不上用場了。
但其實不是被取代，而是 「與人互動、溝通、理解」的能力被放大了價值。

社會學者 Bruno Latour 曾提出一個有趣的問題：我們真正關注的究竟是 matter of fact，還是 matter of concern？

• Matter of fact，在這個例子裡，就像是網站本身要用react還是next、PWA該如何實現，style 應該要用 tailwind 還是 styled component。

• Matter of concern，則是我們如何去關注重要的議題：如何與使用者一起挖掘真正重要的功能？這項產品服務的對象是誰？我們做的每一件事情，能不能推動使用者開始關注重要焦點？

在 Vibe Coding 的時代，我相信 系統設計與運維的能力會更加重要，因為這些是基礎建設。但同時，更重要的是：站在使用者角度思考，翻譯他們的需要，真誠地希望做出能幫助人的產品。

網址再次附上 👉 prayer.simtaiwan.org 一起為世界禱告
也歡迎參與貢獻：https://github.com/Fruitful-Tools/sim-weekly-prayers

如果你正在找一份可以安安靜靜寫程式、不需要太多溝通的工作，老實說——Ubiquiti Cloud Team 可能不適合你。

年輕的工程師通常在意的是能不能學習、有沒有人帶；而資深工程師，則更看重領域的深度與發揮空間。這兩種我都理解，也都經歷過。在 Ubiquiti Cloud Team，工作確實不輕鬆，問題通常也不單純。但如果你追求挑戰、在意技術如何帶出產品價值，這裡就是個能讓你不斷磨練、逐步放大的舞台。

一些基本資訊先講清楚：我們使用 GitHub，開發環境現代化，雲平台該用的都有；團隊內部提供各種 AI coding 工具輔助日常開發（包括我本人非常依賴的 ChatGPT, Cursor 和 Claude Code）；工作型態彈性大，遠端、無限假、健身補助。

一切從「真實世界的裝置」開始

Ubiquiti 跟多數純軟體公司不太一樣，我們的雲端服務是為了支援全球各地數以百萬計的實體網通設備：從 AP、路由器、交換器，到監控攝影機、IoT gateway，甚至還有電力供應管理器。這些設備部署在咖啡店、學校、醫院，還有個人的家裡。

我們團隊的任務，就是讓這些設備背後的雲端控制平台穩定又好用。這看起來像是「寫 API、接資料庫、做 UI」這類常見的工作，但實際上，每一段 API call、每一筆資料同步，背後都連動到一個現實世界中正在運作的裝置。我們的思考總是以終為始：這樣做有沒有達到目的，哪些裝置受到影響，部署的策略又是怎麼樣？怎樣做好風險管控？

有些決定做錯了就回不了頭，但是在這裡步調很快，影響的使用者又很廣，我們常常要思考，能不能在可控的風險底下，做出可進可退的決定，怎樣逐步的rollout，怎樣持續監測。

這種「我寫的程式現在就影響到某人家的網路有沒有通」的感覺，很真實、很有壓力，也很有成就感。在這裡工作，沒有所謂的「純工程師」。每個人都在思考架構，思考使用者。

技術風格與文化：高度自主、強調Ownership

Ubiquiti 的文化跟我以前待過的公司都不一樣。

我待過新創，跟著 MoBagel 從10個人成長到70個人。在那裡很多事情都是我說了算，一個晚上就可以生出一條新的產品線。後來在 Dell 400個人的 Global team，在那裡有大量的跨團隊，跨國，跨層級的溝通，還有硬體文化與軟體文化的隔閡要跨越。

Ubiquiti工作的感受在這兩者之間。當然不可能自己說要上一個版本就上（再次強調：我們有上百萬的使用者），但也不會有太誇張的層層的溝通成本。

很多人在面試時都會問：「你們公司的技術文化怎麼樣？」這是一個很常見也很重要的問題，但其實我常常在想——大家口中的「技術文化」到底是什麼意思？

有些人會把技術文化等同於：你們有沒有寫 Unit Test？文件寫得完不完整？PR 有沒有人幫忙 Review？有沒有 CICD？Roadmap 是怎麼規劃的？這些都很實際，也都重要，但我在 Ubiquiti 工作後，有一個更深的體會。

這是我待過技術文化最健康的公司之一。對，問題也還有很多，可以改善的空間還有很多，多到說不完。但是我仍然會說這是我待過技術文化最健康的公司之一。

我們的文件寫得非常完整；測試也不是應付差事，而是真的能幫助維護品質；PR review 非常認真，夥伴們會提供誠懇又具建設性的 feedback，而且這些 review 常常不只是寫法對錯，還包含對系統整體影響的思考。但這一切都不是靠規定、SOP、或是每天 standup 打卡出來的，而是來自大家對於技術品質的高度自我要求。

簡待來說，公司的技術文化，其實是每一個個人貢獻者的堅持與共識底下去創造出來的。

我曾在新創公司當技術研發總監，也在 DELL 那種超過 400 人的全球研發團隊工作過。自己也寫過不少開源專案。我很在意技術文化，但必須說，Ubiquiti 讓我看見的是，技術文化最有效率地推動方式，其實是buttom-up。Hire 對的人，不僅僅是在意的人，而且是可以主動解決問題的人，最後反而大家更加輕鬆。

這樣的文化不是靠「被動適應」能維持的。我們期待加入團隊的人，不只是來享受這個環境，而是能夠「共同維護、甚至改善」這樣的文化。

工程師不只是寫程式，而是參與產品

很多時候，我們不只是「接到 spec 就照做」，而是反過來主動提出：「這樣設計其實對裝置端沒那麼友善」、「我們可以把這個流程拉平，減少使用者等待時間」……這類建議很多時候會被採納，甚至讓產品設計更貼近實際情境。

如果你也好奇 Ubiquiti 的雲端工程文化…

我會說這是一個很適合喜歡 ownership、又不怕面對真實世界 challenge 的工程師來的地方。你會每天被各種新情境刺激大腦，也會學到如何跟 device team、frontend team、support team 一起打造一個「真的會被用、而且被重度使用」的產品。

在這裡，不只是 coding，更多的是思考與設計。而最棒的是，你寫的每一行程式，最終都會ship給上百萬的使用者。我自己家裡跟教會也都換成了整套的Ubiquiti網路設備，這樣方便的可監控性還有靈活的遠端設定，真的是有打中我們這種IT prosumer的心。

When I first started building websites, everything was manual. Spin up a VM, install packages, configure Apache, set up networking—line by line, hoping I didn’t miss a step. It worked, but it was fragile.

Then Docker came along. Suddenly, I could package everything into one neat container. Docker Compose made it even better—I could describe my whole stack in a single YAML file. Kubernetes took it further by orchestrating all the moving parts for me. And when Terraform arrived, it felt like magic: I wasn’t scripting servers anymore, I was declaring what I wanted, and the system figured out the rest.

At the time, I just appreciated the convenience. What I didn’t realize was that I was stepping into a world perfectly suited for AI.

Why Declarative Thinking Matters

Declarative tools like Docker, Kubernetes, and Terraform flip the script. Instead of telling machines how to do something, we describe the end state. The system takes responsibility for figuring out the steps to get there.

Take infrastructure. Back in the old days, I’d write long bash scripts: install Postgres, configure users, set up storage, open the right ports, and hope I hadn’t missed a detail. Every line was an instruction tied to a particular OS, version, or runtime. For an AI trying to understand this, it’s like reading a recipe where half the ingredients are hidden between the lines—you need deep contextual knowledge just to interpret what’s happening.

With Terraform, I can instead declare:

resource "aws_db_instance" "mydb" {
  engine            = "postgres"
  instance_class    = "db.t3.micro"
  allocated_storage = 20
}

That snippet is compact but unambiguous. It says, “I want a Postgres database of this size and type.” AI doesn’t need to parse ten steps of installation logic—it just sees the goal. Because declarative code describes what something is rather than how to do it, it maps naturally onto how AI models understand text: as patterns, relationships, and outcomes.

The same is true in UI. In the old CSS days, I’d have a spaghetti of selectors, nested rules, and overrides—difficult for me to reason about, and almost impossible for an AI to modify without breaking something. But with Tailwind, I can write:

<button className="bg-blue-600 rounded-lg hover:bg-blue-700">
  Submit
</button>

Every class is atomic, precise, and predictable. Change bg-blue-600 to bg-green-600, and the background color only changes—no side effects lurking elsewhere. For an AI, this is huge: it can confidently generate changes knowing the outcome is deterministic.

This is why declarative paradigms are so AI-friendly. They reduce ambiguity, eliminate hidden state, and separate intent from implementation. Instead of reverse-engineering “what the human really meant” from dozens of imperative steps, AI can work directly with clear, human-readable declarations of the desired outcome.

Writing Code That AI Can Understand

Over the years, I’ve noticed that the practices making my code easier for teammates also make it easier for AI. Some practical shifts stand out:

• Vertical slice architecture: Organizing by features instead of layers gives both humans and AI self-contained units of meaning.

• llms.txt files: Just like robots.txt tells crawlers what to do, llms.txt gives AI a roadmap for your project.

• AI-actionable docs: Instead of vague “configure the DB,” I now write: “set DATABASE_URL=postgres://user:pass@host/db.” Instead of writing click this link in the document, we can write run curl -XPOST ... so AI doesn’t guess—it executes.

• Composable components: Smaller, reusable parts reduce the chances of AI (or me) breaking things when making changes.

Toward a Shared Language Between Humans and AI

Looking back, I realize Docker, Compose, K8s, and Terraform weren’t just conveniences. They were rewiring how I think about code. Declarative, modular, predictable—exactly the qualities that make AI collaboration possible.

The shift is bigger than tools. It’s about our role. We’re no longer just code writers. We’re system architects, orchestrating intelligent collaboration between humans and machines.

That’s the real “declarative revolution.” It’s not just how we deploy apps or style UIs—it’s a new way of thinking about programming itself. A shared language between us and AI.

And once you see it that way, it’s hard not to imagine what the next decade of coding will look like.

在沒寫一行 code 的情況下，我使用 lovable 完成了一個有互動、有設計感、有行動體驗的網站，而且只花了 20 分鐘。

成品：https://2025-bible-reading.fruitful-tools.com/

我不是第一次做網頁，但這次是我第一次不用打開 VSCode/Cursor，甚至是一邊單手抱著四個月大的寶寶、一邊語音輸入指令完成的。

🎯 這次的任務：做出一個讀經計畫 Web App

這個網站的目標很簡單：

• 本來就在今年為教會設計了一年 12 個月份的讀經計畫

• 每個月一張讀經卡（正面是計畫，背面是設計圖）。本來列印成酷卡，但是因為數量不足，後來有些人拿不到了，才想說設計成網頁。

• 手機優化、預設繁體中文

這些需求，你交給設計師畫圖、前端寫 code、PM 排進開發時程，可能要 1~2 週才會上線。如果你是很優秀的前端工程師，可能也要花三四個小時。但是我只做了一件事：跟 lovable.dev 說清楚我要什麼。

🧠 怎麼跟 AI 說？我的語音指令長這樣：

please use the following tech stack 
React 19, Tailwind CSS v4, Vite, TypeScript, React Router v7, 
ShadCN/UI, Framer Motion 
 
I wish to create a yearly bible reading plan app, purely frontend. 
I will upload 24 images, 12 as monthly bible reading calendar, 12 are designs related to that month's scope. 
Create a website that has 12 months as 12 cards. 
When a card is clicked, show the calendar png. 
When clicked again, flip the card to show design. 
Make it a web app. 
Greenish design. 
i18n with default to 繁體中文.

其實這第一步的指令，應該是對非工程師來說最困難的地方。因為一開始選擇什麼樣的「網頁技術套件」，會大大影響後續網站的可維護性與延展性。 這邊分享我下的 tech stack 指令。這一段是我以前在帶開發專案時，反覆磨出來的經驗組合 — — 既要現代、要快，又要容易整合元件庫與動畫，也要讓後面維護不頭痛。

這代表：跟工程師問清楚技術架構，描述你想要什麼，AI就能幫你開工。

上面AI沒有尊重我說喜歡綠色，並且要繁體中文的功能。可能一次講太多了，所以提示一下

I wish to have greenish design, 
and I want i18n with default to 繁體中文

中間有個小bug出現，我無腦點一下叫他修，然後就87%完成了。

📦 上傳素材（最近才release的功能）：24 張圖片，AI 自動分類

我事先準備好了 24 張圖：1~12 月份的「讀經表」（正面）與「設計圖」（背面），檔名就是 1.png ~ 24.png。

我跟 AI 說：

I uploaded january's front and back image (1.png and 2.png), 
february is 3.png and 4.png, ...etc

就這樣，它自己處理好了。

🔧 指令微調與問題修正（像在帶專案一樣）

過程中，我發現幾個 UX 問題，於是直接「改需求」：

1. 改進手機 UX：圖片載入時要有明確提示

When I click on the calendar card and there is a pop-up, 
the image is loading in real time, 
but the visual effect is not clear that it’s loading. 
Could you improve the user experience on this issue?

AI 立刻改了，圖片還沒載好時會顯示 loading spinner，避免使用者卡住。

2. 小bug：修正翻頁動畫

upon click month card, the calendar card is shown in the popup. 
I wish to flip to the back side (the design) 
when I click the image in the popup. 
There should be an animation of flipping card

3. 加入「月份解鎖機制」

我希望未來的月份不能點擊，增加一點期待感：

Can you lock each month's card until 1 month before? 
For example, user can not click on September until August.

AI 做到了，還會自動根據目前時間決定哪幾個月可點。

Lovable也把 custom domain 整合的很好，這塊我就不詳述了，請官方文件，基本上也是點一點就出來了。

一個可以 demo 的產品

不到 30 分鐘，我就能拿出一個可以 demo 的 Web App：

• 行動裝置支援好

• 有 loading 狀態

• 卡片翻面動畫自然

• 根據月份解鎖

• 用繁體中文顯示

• 無須後端，Custom domain跟 Cloudflare 整合又方便又快

這個專案的價值不在技術，而在：我們把想法轉為實體產品的門檻，降到前所未有的低。

末了的話

• 給產品經理：POC不用找設計師了，先看看 AI 有沒有懂你吧。

• 給老闆或接案公司：這個世界距離又快又穩又好的日子越來越靠近了。

• 給父母：如果你需要一手抱寶寶，一手寫code，就用講的把網頁講出來吧。不要再害怕生小孩了！

即便透過觀念上的解釋：MCP AI Agent在紅什麼，不自己動手做做看，可能還是很難了解AI Agent到底是什麼。這篇文章手把手教你用MCP Server建制一個AI Agent，連接Goose或者使用Claude Desktop使用你的AI Tool。

(專案代碼在這邊)

建制你的MCP Server專案

安裝uv (python package manager): https://docs.astral.sh/uv/getting-started/installation/，確認你的uv安裝路徑

which uv 
# 我的路徑在 ${HOME}/.local/bin/uv

初始化專案

uv init --package mcp-server-demo 
cd mcp-server-demo 
uv add "mcp[cli]" pydantic loguru faker

使用你的IDE/編輯器創建

# src/mcp_server_demo/server.py 
 
import random 
from loguru import logger 
from mcp.server.fastmcp import FastMCP 
from faker import Faker 
 
fake = Faker() 
 
# Create an MCP server 
mcp = FastMCP("mcp-server-demo") 
 
# Add an addition tool 
@mcp.tool() 
def get_order_info(order_id: str) -> dict: 
    """Get the status of an order""" 
    status = ["success", "delayed", "cancelled", "pending_payment"] 
    order_info = { 
        "order_id": order_id, 
        "status": random.choice(status), 
        "client_email": fake.email(), 
    } 
    logger.info(f"Order info: {order_info}") 
    return order_info 
 
 
@mcp.tool() 
def send_coupon_to_user(order_id: str, customer_email: str) -> str: 
    """Send a coupon to the user to make user happy""" 
    logger.info(f"send coupon to {customer_email} for order {order_id}") 
    return f"Coupon sent to {customer_email}"src/mcp_server_demo/__init__.py

# src/mcp_server_demo/__init__.py 
 
from .server import mcp 
from loguru import logger 
 
def main() -> None: 
    logger.info("Starting MCP server demo") 
    mcp.run() 
 
 
if __name__ == "__main__": 
    main()

# src/mcp_server_demo/__main__.py 
 
from mcp_server_demo import main 
 
main()

測試一下 uv run mcp-server-demo

看到這些訊息就表示成功囉，可以ctrl + C關掉他了

安裝 Goose

從Goose官方文件安裝: https://block.github.io/goose/docs/quickstart

Goose 是一個開源的 MCP 客戶端，讓你可以配置自己的 LLM 提供者（使用 API 金鑰），在自己的機器上運行，並與你的 AI 代理（MCP 伺服器）互動。

如果你沒有任何LLM金鑰，也無法搭載本地的LLM，可以下載 Claude Desktop，用你的免費額度來玩玩看：https://modelcontextprotocol.io/quickstart/user

在Good 上面設定你的 LLM 供應商：https://block.github.io/goose/docs/getting-started/providers

打開Goose設定 -> Add custom extensions

Command那邊要放 {path to uv} run {path to your project}/.venv/bin mcp-server-demo

按Add，可以加入

實際場景

如果我們問了一個不清不楚的問題（沒有提供訂單資訊），透過工具提供的資訊，Goose可以請我們提供詳細資訊

當我們詢問某一筆延遲的訂單，系統主動告訴我們要不要使用coupon工具發放優惠卷，並且使用訂單查到到使用者email進行發放

如果我說好，系統還可以讓我手動審核同意再行動

下一步

看見AI Agent怎樣和Chatbot互動，應該更可以了解AI Agent的價值了吧！傳統軟體開發通常由後端整合第三方服務，前端負責 UI/UX，確保使用者體驗。但這種方式要求開發者掌握所有邏輯，並自行串接各種服務，以維持完整控制權。

隨著生成式 AI（Generative AI）與 AI Agent 的發展，設計思維開始轉變。我們可透過 AI Agent 定義業務邏輯，並透過標準化協議（如 Anthropic 的 Multi-Context Protocol, MCP）管理 AI 與 LLM（大語言模型）的互動。這讓開發者無需關注傳統的後端邏輯與前端開發，而是專注於 AI Agent 的行為設計，讓 AI 自主處理任務。

這種模式提升了開發靈活性，特別適用於快速驗證新想法（Prototype）。開發者只需定義 AI Agent 的核心功能，而無需投入大量時間與資源搭建完整的前後端架構，透過 MCP 標準化的互動，即可快速落地應用。

接著你可以：

1. Fork 專案自己來玩玩看：https://github.com/schwannden/mcp-server-demo

2. 看看 MCP 官方的 Reference Server: https://github.com/modelcontextprotocol/servers

3. 加入Goose Discrod看看其他人在做什麼酷酷的事情：https://discord.com/invite/block-opensource

(This is a chat gpt tranlated article from: https://medium.com/@schwanndenkuo/mcp-ai-agent%E5%9C%A8%E7%B4%85%E4%BB%80%E9%BA%BC-e7fd2523c749)

(If you would rather like to start building your own AI agent, checkout: AI Agent 0 到 1: MCP Server with Goose）

Background Story

As large language models (LLMs) like ChatGPT, Claude, and Gemini continue to evolve and become more powerful, the question arises: where is AI headed in the future? Tech industry leaders such as Andrew Ng, Elon Musk, and Jensen Huang have all pointed out that “AI Agents will be the next major milestone.” But what exactly is an AI Agent?

With more and more LLM providers offering advanced models and applications, we naturally wonder: is there an open and universal protocol that allows us to create AI Agents freely without being locked into a specific platform or provider?

Limitations of LLMs

When we use LLMs like ChatGPT or Claude, we can ask questions and have conversations, but they can’t actually “do” anything. For example, you can’t directly ask ChatGPT to book a restaurant, send an email, or fetch a report from your home NAS.

This is where AI Agents come into play. An AI Agent acts like a personal assistant that not only converses with you but also takes real actions based on your needs. For instance, if you want to know when a particular colleague last logged into your company’s system last month, a standard LLM wouldn’t be able to help because it lacks access to your company’s internal data. However, an AI Agent can accomplish this by calling the company’s internal APIs or querying the database to retrieve the relevant information instantly.

Another limitation of LLMs is that their responses are confined to their pre-trained knowledge. If you ask about a breaking news event or specific business data within your company, an LLM will often be clueless. To address this, we might use Retrieval-Augmented Generation (RAG), which allows an LLM to “look up” additional data before responding. However, RAG works best when dealing with relatively static, infrequently changing data. For real-time or dynamic requests — such as checking the current shipping status of a customer’s order — RAG can be slow and costly.

On the other hand, an AI Agent functions like a real-world assistant that can handle tasks dynamically. If you ask, “Where is my order #12345 right now?” the AI Agent can immediately call your company’s logistics system API to provide a real-time, accurate response.

Summary

• General LLMs act like “knowledgeable encyclopedias” that provide answers based on their training data but cannot take action.

• RAG-enhanced LLMs function as “encyclopedias with a database,” useful for retrieving external data but not ideal for real-time scenarios.

• AI Agents work like “assistants that can take action,” using tools and APIs to solve specific, real-time problems.

Limitations of AI Agents

1. Interoperability Issue:
   With the rise of multiple LLM providers like Claude, Gemini, and OpenAI, AI-powered applications have diversified — from chatbots like ChatGPT to intelligent IDEs like Cursor. However, ensuring that an AI Agent can seamlessly integrate across different platforms is challenging. Ideally, we need a standardized protocol that allows an AI Agent to work flexibly across various platforms without being tied to a specific model or service provider.

2. Limited Adaptability for Automation:
   Traditional AI Agents are designed primarily for human users — meaning they operate step by step based on user commands or predefined workflows. This limits their flexibility when used by other machines (such as client applications or automation services). Ideally, applications should be able to dynamically select and orchestrate different AI Agent tools based on real-time needs, rather than following rigid, pre-scripted sequences.

How MCP (Anthropic’s Model Context Protocol) Solves These Issues

MCP introduces a standardized client-server architecture that effectively addresses these challenges. Developers can focus on creating independent function modules, known as MCP Servers, which handle specific tasks such as sending emails, managing calendars, or performing image recognition. Meanwhile, applications that integrate with LLMs — such as Claude Chatbot or intelligent IDEs like Cursor — act as MCP Clients. These MCP Clients can dynamically explore and identify available functionalities provided by MCP Servers, selecting the most appropriate tools for complex tasks.

This structured collaboration makes AI Agents more interoperable, easier for machines to understand, and seamlessly automatable, enhancing the flexibility and efficiency of the entire AI ecosystem.

Real-World Workflow Example

Imagine you’ve built an AI customer service chatbot using MCP that integrates two tools:

1. Order Tracking Tool — Connects to your company’s database to check order status based on a provided order number.

2. Coupon Issuance Tool — Dynamically decides whether to issue discount coupons if a customer is dissatisfied.

Scenario: A Customer Inquiry

A customer asks the AI chatbot:
“My order #12345 has been delayed for two weeks. Can you check on it for me?”

1. MCP Client (e.g., Claude Chatbot) analyzes the request and determines that it needs external tools to complete the task.

2. It dynamically queries the MCP Server to check what tools are available.

3. The MCP Server responds with a list of available tools and how to use them.

4. The AI decides to first call the Order Tracking Tool, using order number #12345 to check the status.

5. Suppose the response indicates “Shipment delayed, not yet dispatched.”

6. The LLM understands that the customer might be dissatisfied, so it calls the Coupon Issuance Tool to offer compensation.

7. The AI chatbot responds: “Your order is delayed due to a logistics issue. We sincerely apologize for the inconvenience. As a token of our apology, we’re offering you a discount coupon.”

Now, if the order status instead showed “Payment not completed.”

• The AI would not issue a coupon since the issue isn’t a shipping delay.

• Instead, it would respond: “Your order is awaiting payment. Please complete the payment, and we will process the shipment immediately. Thank you!”

In this scenario, we didn’t need to manually code logic for every possible situation. By simply providing MCP Server tools, the LLM itself can dynamically decide which tools to use to resolve issues intelligently.

Frequently Asked Questions (FAQ)

Q: Who developed MCP?

A: MCP was introduced by Anthropic as a protocol that enables AI models to interact more flexibly with external tools. However, MCP is not exclusive to Anthropic’s AI models (e.g., Claude) but is designed as an open, vendor-agnostic standard that any AI model can use.

Q: How does MCP work?

A: The workflow follows these steps:

1. The MCP Client (e.g., Claude, Goose, etc.) sends a request to the MCP Server.

2. The MCP Server responds with available tools, resources, and prompts.

3. The MCP Client determines which tools to use and what data to provide to the AI model to fulfill the user request.

This allows AI to dynamically select and combine different tools to complete tasks more efficiently.

Q: Is MCP limited to Claude?

A: No. While Claude Desktop is an MCP Client developed by Anthropic, MCP itself is not tied to any single AI vendor. For example, Goose is a rapidly growing MCP Client that supports integration with various LLM APIs and features an MCP Server marketplace offering a variety of tools.

Q: Are there security risks with MCP? How can we ensure its security?

A: MCP does not require sending sensitive data to AI models by default. Security depends on how MCP Servers manage data transmission. Best practices include:

• Access control: Restrict API and tool access to prevent data leaks.

• API key management: Securely store and manage API keys to prevent unauthorized access.

• Monitoring and auditing: Track API calls and data access to detect and mitigate security risks.

By following these practices, MCP can be implemented securely while maintaining data integrity.

Useful Resources

• MCP Official Website

• MCP Reference Servers

• List of MCP Clients & Supported Protocol Features

（比起觀念的了解，如果你想要直接動手，請看：AI Agent 0 到 1: MCP Server with Goose）

故事背景

隨著 ChatGPT、Claude、Gemini 等大型語言模型（LLM）不斷推陳出新、能力越來越強大，AI 的未來究竟會往哪裡發展呢？科技圈重量級人物，如 Andrew Ng、Elon Musk 和黃仁勳都紛紛指出：「AI Agent 將會是下一個重要的里程碑。」那麼，大家口中的 AI Agent 到底是什麼呢？

然而，當越來越多 LLM 廠商提供各種強大的模型與應用時，我們不禁好奇：有沒有一個開放且通用的協議（Protocol），能讓我們自由創造各種 AI Agent，而不用擔心被某個特定平台或廠商綁住呢？

傳統軟體開發通常由後端整合第三方服務，前端負責 UI/UX，確保使用者體驗。但這種方式要求開發者掌握所有邏輯，並自行串接各種服務，以維持完整控制權。隨著生成式 AI（Generative AI）與 AI Agent 的發展，設計思維開始轉變。我們可透過 AI Agent 定義業務邏輯，並透過標準化協議（如 Anthropic 的 Multi-Context Protocol, MCP）管理 AI 與 LLM（大語言模型）的互動。這讓開發者無需關注傳統的後端邏輯與前端開發，而是專注於 AI Agent 的行為設計，讓 AI 自主處理任務。這種模式提升了開發靈活性，特別適用於快速驗證新想法（Prototype）。開發者只需定義 AI Agent 的核心功能，而無需投入大量時間與資源搭建完整的前後端架構，透過 MCP 標準化的互動，即可快速落地應用。

LLM的限制

我們平常用 ChatGPT 或 Claude 這些大型語言模型（LLM）時，通常只能問問題或聊天，但沒辦法讓它們真的「做」什麼事。比如說，你不能直接叫 ChatGPT 幫你訂餐廳、寄 email，或去你家 NAS 裡抓一份報告。

這時候，「AI Agent」就派上用場了。AI Agent 就像是一個貼心的小秘書，不僅能和你對話，還能根據你的需求實際「動手做事」。舉例來說，如果你想知道上個月某個同事最後一次登入公司系統是什麼時候，一般的 LLM 是答不出來的，因為它不懂你公司內部的資料。但是 AI Agent 可以做到，它會直接去呼叫公司內部系統的 API 或查詢資料庫，立刻幫你找到準確的紀錄。

另一方面，LLM 的另一個問題是，它回答問題的能力侷限在自己所學過的知識內。如果碰上了最新發生的新聞，或者你自家的業務資訊，LLM 常常束手無策。為了解決這個問題，我們可能會想到 RAG（Retrieval-Augmented Generation，檢索增強生成），讓 LLM 能夠先去「翻閱」額外的資料再回答問題。不過，RAG 適合的情境是資料相對靜態、變動不頻繁的情況。如果你有些即時的、動態的需求（比如即時查詢某個顧客訂單的出貨進度），用 RAG 不只緩慢，還可能成本太高。

而 AI Agent 就像是幫你跑腿的小助手，你只要給它明確的任務，例如：「幫我確認訂單 12345 現在寄到哪裡了？」它會馬上呼叫你公司物流系統的 API，給出即時又正確的答案。

總結一下：

• 一般的 LLM 就像「聰明的萬事通先生」，只能提供他知道的答案，而且只動口，不動手。

• RAG 就像是「帶著資料庫的百科全書」，但資料庫通常比較靜態，不適合需要即時資料的情境。

• AI Agent 則像是「能跑腿、能幫你辦事的小秘書」，根據你提供的特定工具或 API，解決具體、即時的問題。

AI Agent的限制

AI Agent 面臨的第一個限制是「通用性」的問題。隨著越來越多的 LLM 廠商（如 Claude, Gemini, OpenAI 等）湧現，基於這些模型打造的應用程式也越來越多元：從最常見的 Chatbot（如 Claude、ChatGPT）到更複雜的智能 IDE（如 Cursor），我們很難確保自己開發的 AI Agent 能夠無縫地在各種不同的平台或環境中運作。理想上，我們希望有一套標準協議，讓同一個 AI Agent 可以輕鬆地與各個平台整合，不必受限於特定的模型或服務供應商。

AI Agent 面臨的第二個限制，是過去的設計往往只適合讓「人」來使用。使用者指示一步，AI Agent 就執行一步，或者必須按照預先定義好的流程才能運作。這樣的設計對「機器」（例如用戶端應用程式或自動化服務）來說不夠彈性。應用程式難以智能地根據需求動態選用不同的 Agent 工具，更別提自動判斷使用順序。

MCP（Anthropic Model Context Protocol）提供了一個標準化的 Client–Server 架構，完美地解決了這兩個問題。透過 MCP，開發者只需專注於製作各自獨立的功能模組，這些模組稱為 MCP Server，例如發送 Email、管理行事曆或進行圖像辨識等特定任務。另一方面，整合 LLM 的應用程式，例如 Claude Chatbot 或智能 IDE Cursor 等，則扮演 MCP Client 的角色。這些 MCP Client 能夠透過 MCP Server 提供的標準化介面，動態地探索和識別可用的功能與工具，並根據使用者或應用需求智能地排列組合、選擇最合適的工具來完成複雜任務。

透過這種分工與協作的架構，MCP 讓 AI Agent 變得更具通用性，也更加容易被機器理解與自動化整合，使得整個 AI 生態圈能夠更加靈活且高效地運作。

實際的工作流程：

假設今天你透過MCP建立了一個AI客服機器人，它整合了兩個工具：

1. 訂單查詢工具：可以連接你的公司資料庫，根據客戶提供的訂單編號查詢訂單狀態。

2. 優惠券發送工具：當客戶遇到不滿意的情況時，AI能夠動態地決定是否給予折扣優惠券。

1. 一位顧客向AI客服詢問：「我的訂單 #12345 已經兩週了還沒有收到，可以幫我查一下嗎？」

2. 此時MCP Client (例如Claude Chatbot)透過內建的LLM分析使用者需求，知道需要透過工具來完成此任務。它動態地向 MCP Server詢問：「目前有哪些工具可用？」

3. MCP Server 回傳目前可用的工具清單和使用方式給Client。

4. AI判斷後，決定先呼叫訂單查詢工具，透過客戶提供的「#12345」查詢訂單狀態。

假設訂單狀態顯示：「出貨延誤，尚未寄出」。

1. LLM理解顧客可能會因此不滿意，於是動態地決定再透過優惠券發送工具向顧客提供一張優惠券，作為補償。

2. 最終AI客服回覆顧客：「您的訂單因為物流延誤尚未寄出，造成您的不便，我們深感抱歉，特別贈送您一張折扣優惠券以表歉意。」

假設訂單狀態顯示：「尚未付款」。

1. LLM理解此情境並非出貨問題，而是付款問題，因此不會發送優惠券，而是提醒顧客完成付款。

2. 最終AI客服回覆顧客：「您的訂單尚未完成付款，請您完成付款後，我們將立即為您安排出貨，謝謝！」

在這樣的場景中，注意，我們不需要去提供情境判斷的邏輯，只要透過MCP Server提供兩個工具，LLM自己有辦法依照情境判斷要使用哪些工具解決問題。

常見問題

Q：MCP 是由誰開發的？
A：MCP 是由 Anthropic 公司提出的一套協議，目的是讓 AI 模型能夠更靈活地與外部工具互動。不過 MCP 並不限於 Anthropic 自己的 AI 模型（如 Claude），而是開放且獨立於特定 AI 廠商的標準，因此任何符合 MCP 的模型都能搭配使用。

Q：MCP 的工作原理是什麼？
A：MCP 的工作流程大致如下：

1. MCP Client（例如 Claude、Goose 等）會先向 MCP Server 發出請求。

2. MCP Server 會回應並告訴 Client 有哪些工具（tools）、資源（resources）及提示訊息（prompts）可用。

3. MCP Client 根據 Server 提供的資訊，智慧地判斷該使用哪些 API，並決定要提供什麼樣的資料給 AI 模型，以滿足使用者的需求。

透過這樣的架構，AI 能更靈活地自動選擇、組合不同的工具來完成任務。

Q：MCP 是否一定要搭配 Claude 使用？
A：並不一定。Claude Desktop 雖然是 Anthropic 開發的一款 MCP Client，但 MCP 本身並不侷限於任何單一 AI 廠商或模型。我個人推薦可以嘗試 Goose，它是一個近期非常熱門的 MCP Client 實作，不但可以自由接入各家 LLM API Key，團隊也積極發展 MCP Server 市集（Marketplace），提供豐富的工具與資源。

Q：使用 MCP 會有安全風險嗎？該如何確保 MCP 的安全性？
A：MCP 本身並不會強迫將敏感資料傳送到 AI 模型端，而是完全由 MCP Server 決定資料的傳輸範圍。因此，確保 MCP 安全性的重點在於如何設定與管理 MCP Server，具體包含：

• 權限控制：透過細緻的權限管理，嚴格限制每個 API 或工具能存取的資料範圍，防止敏感資料外洩。

• API 金鑰管理：妥善保管 API 金鑰，避免外流，同時採用安全的金鑰儲存與管理機制。

• 監控與記錄：對每一次 API 呼叫與資料存取進行監控，透過定期的記錄與稽核，掌握系統狀態，快速發現與處理潛在的安全問題。

透過以上措施，即可有效控制 MCP 可能的安全風險，保障資料安全性與系統穩定性。

好用資源

1. MCP官方網站

2. MCP Reference Servers

3. MCP Clients 跟每個 Client 目前支援的 protocol範圍

4. 自己動手做一個MCP Server吧

The Challenge of Searching Large Tables in Django Admin

At Ubiquiti, our systems often deal with enormous datasets — tables with over 1 billion records are not uncommon. While Django Admin is a powerful tool for managing and interacting with data, its default search functionality can become a bottleneck in these scenarios. The built-in icontains query used in search_fields scans every column included, leading to sluggish performance as the dataset scales.

Consider a user management table with billions of records:

• We want email prefix search to quickly locate users whose email addresses start with a specific term (e.g., searching for john@domain.com should instantly find matches).

• We also want email alias search that identifies aliases for a given email using regular expressions (e.g., searching for schwannden@gmail.com should also return schwannden+test1@gmail.com and other variants).

• We also want to search user by UUID, using index would be very fast in support cases when we can obtain user’s UUID.

Here’s the catch:

• These two searches are independent use cases by. A regex-based alias search is computationally expensive and shouldn’t be performed unless explicitly needed.

• Django Admin’s get_search_results function only accepts a single search_term, making it impossible to differentiate between the prefix search and alias search.

To make matters worse, adding multiple search fields by overwriting the change_list template doesn’t help because Django passes all queries through the same q=<some search term> parameter, preventing us from distinguishing between search types.

The Solution: Adding Custom Filters for Large Tables

The Django list_filter feature could be an ideal solution for custom filtering logic. However, its default implementation generates choices for filtering, which is impractical for fields like UUIDs or emails where precomputing billions of choices is infeasible.

This problem led us to explore a creative approach to customize the list_filter component and integrate specialized search functionality directly into the Django Admin interface. After much research, we came across a post that inspired us to extend Django’s list_filter to support dynamic input fields for our custom search needs.

Here’s how we implemented it:

Create a Custom Input Filter Template

First, we added a new template to render input fields dynamically in the admin filter area.

Create the file templates/admin/input_filter.html:

{% load i18n %} 
 
<details data-filter-title="{{ title }}" open class="filter-item"> 
    <summary> 
      {% blocktranslate with filter_title=title %} {{ filter_title }} {% endblocktranslate %} 
    </summary> 
    <ul> 
        <li> 
            {% with choices.0 as all_choice %} 
            <form method="GET" action=""> 
                {% for k, v in all_choice.query_parts %} 
                <input type="hidden" name="{{ k }}" value="{{ v }}" /> 
                {% endfor %} 
                <input 
                    type="text" 
                    value="{{ spec.value|default_if_none:'' }}" 
                    name="{{ spec.parameter_name }}"/> 
                {% if not all_choice.selected %} 
                    <strong><a href="{{ all_choice.query_string }}">⨉ {% trans 'Remove' %}</a></strong> 
                {% endif %} 
            </form> 
            {% endwith %} 
        </li> 
    </ul> 
  </details>

2. Define an InputFilter Base Class

Next, we created an InputFilter class to manage custom input fields:

class InputFilter(SimpleListFilter): 
    """ 
    Base class for filters that take a text input 
    """ 
 
    template = "admin/input_filter.html" 
    parameter_name: str 
    title: str 
 
    def lookups(self, request, model_admin): 
        # Dummy, required to show the filter. 
        return ((),) 
 
    def choices(self, changelist): 
        # Grab only the "all" option. 
        all_choices = super().choices(changelist) 
        try: 
            all_choice = next(all_choices) 
            all_choice["query_parts"] = ( 
                (k, v) for k, v in changelist.get_filters_params().items() if k != self.parameter_name 
            ) 
            yield all_choice 
        except StopIteration: 
            return  # Clean exit when no values remain 
 
    def queryset(self, request, queryset): 
        value = self.sanitized_value() 
        if value is not None: 
            return queryset.filter(**{f"{self.parameter_name}": value}) 
        return queryset 
 
    def sanitized_value(self): 
        value = self.value() 
        if value is None: 
            return None 
        return value.strip()

With this base filter, we can now inplement our own filters, we can use parameter_name to overwrite the way we wish query is made, and we could overwrite def queryset to provide more customized search query like finding email aliases.

class UUIDFilter(InputFilter): 
    """ 
    Filter for UUID exact match 
    Ignore filter if the value is not a valid UUID 
    """ 
 
    parameter_name = "id" 
    title = "By User ID" 
 
    def sanitized_value(self): 
        value = super().sanitized_value() 
        if value is None: 
            return None 
        try: 
            return uuid.UUID(value) 
        except ValueError: 
            return None 
 
 
class EmailFilter(InputFilter): 
    """ 
    Filter for email prefix search on the user model itself 
    """ 
 
    parameter_name = "email__startswith" 
    title = "By Email Prefix" 
 
 
class EmailAliasFilter(InputFilter): 
    """ 
    Filter for email alias search 
    For example, "test+alias@example.com" will be matched by "test@example.com" 
    """ 
 
    parameter_name = "email" 
    title = "Search Email Alias" 
 
    def queryset(self, request, queryset): 
        value = self.sanitized_value() 
        if value is not None: 
            split_result = value.split("@") 
            if len(split_result) != 2: 
                return queryset.none() 
            local_part, domain = split_result 
            # Adjust the local part to remove any existing '+' and its suffix 
            local_part = local_part.split("+")[0] 
            regex = rf"{local_part}(\+.+)?@{domain}" 
            return queryset.filter(email__iregex=regex) 
        return queryset

And in our admin model, we can mix this custom filters with built in field filter like:

class UserAdmin(admin.ModelAdmin): 
    list_filter = (UUIDFilter, EmailFilter, EmailAliasFilter, "is_legacy")

The built in choice filter still work on fields with less options.

Reusing filter

Assuming we have another model with a foreign key poiting to User, and we wish to filter this record by its related user’s email, we simply need to inherit from the original EmailFilter and change the parameter_name

class ShoppingCartUserFilter(EmailFilter) 
    parameter_name = "user__email" 
 
class CartAdmin(admin.ModelAdmin): 
    list_filter = [ShoppingCartUserFilter, "cart_type"]

Bravo: A Scalable Solution

This approach transforms Django Admin’s search functionality into a powerful, scalable tool capable of handling massive datasets efficiently. By introducing customizable filters, you can address diverse search scenarios without compromising performance. Whether managing billions of records or implementing tailored search logic, this method ensures your admin remains user-friendly and lightning-fast.

“By wisdom a house is built, and by understanding it is established; by knowledge the rooms are filled with all precious and pleasant riches.”
Proverbs 24:3–4

Today we dive into this obscure exception: Unhandled exception: An error occurred in the current transaction. You can’t execute queries until the end of the ‘atomic’ block.

What Happened

On a sunny Wednesday, we were excited to release a new version of our service to production, which has around 1k~5k active requests per second. As usual, we monitored for unexpected exceptions that happened, and this popped up a few times: Unhandled exception: An error occurred in the current transaction. You can’t execute queries until the end of the ‘atomic’ block.

The root cause was found quickly, a race condition existed in how one of the tables arehandled, but what troubled us was the strange message that was not helping at all!

Our Original Code

class A(Model): 
    id: int 
 
class B(Model): 
    id: int 
    a: OneToOneField(A, on_delete=models.CASCADE) 
 
def send_event(a): 
    print(f"{a.id} deleted") 
 
def delete_a(a): 
    with @transaction.atomic(): 
        try: 
            a.delete() 
            send_event(a) 
        except A.NotFound: 
            pass # it is ok 
        other_db_query()

Note a race condition could already happen, when 2 requests delete the same instance of A, it is likely that we would send the event twice.

A refactor that creates this obscure exception

We thought making send_event into a signal could help make the main business more clear:

class A(Model): 
    id: int 
 
class B(Model): 
    id: int 
    a: OneToOneField(A, on_delete=models.CASCADE) 
 
@receiver(post_delete, sender=B) 
def send_event(b): 
    a = b.a 
    print(f"{a.id} deleted") 
 
def delete_a(a): 
    with @transaction.atomic(): 
        try: 
            a.delete() 
        except A.NotFound: 
            pass # it is ok 
        other_db_query()

What we expected to happen upon a race condition should be

1. Request 1 delete A instance, cascade delete B, triggers signal in send_event

2. Request 2 delete the same A instance, does the same thing, but finishes first.

3. In request 1, send_event should raise A.NotFound in line a = b.a

4. The exception should be handled as disregarded in delete_a try-catch block.

5. Other query should proceed as normal.

But in fact, we receive this Unhandled exception: An error occurred in the current transaction. You can’t execute queries until the end of the ‘atomic’ block. And the line of error happens in some other DB query. Why?

Django’s Official Warning

In Django’s official document: https://docs.djangoproject.com/en/5.1/topics/db/transactions/#controlling-transactions-explicitly

It states that one should Avoid catching exceptions inside atomic!

Why? Because inside an atomic session, when a DB query failed, it not only raises exception, but it mark the transaction state as being corrupted. This is so that during the __exit__ handling of a with transaction.atomic() context, it can properly rollback the session.

In our case, the exception raised from a = b.a is caught indeed! but the atomic session state has been marked as corrupted. So in some other DB query , we have this obscure exception which is not helpful, and took us a long time to find the root cause.

What should be done in this situation?

Following Django’s document suggestion, if we are to handle an exception within a atomic session, it is best to create a nested session and try catch it. This update will fix the issue

@receiver(post_delete, sender=B) 
def send_event(b): 
    try: 
        with transaction.atomic(): 
            a = b.a 
            print(f"{a.id} deleted") 
    except A.NotFound: 
        pass

Since a NotFound exception is not something that actually breaks the database, we let the inner session handles the rollback (which does nothing), and set the session state back to normal, some that later DB query can be executed normally.

Wrapping It All Up: The Art of Taming Transactions

In high-concurrency systems, even caught exceptions can corrupt transactions. Django’s atomic blocks demand careful handling — use nested transactions to isolate risks and follow framework warnings. Resilient code isn’t just functional; it’s designed for real-world complexity. Remember, every obscure error is a chance to learn and improve.

“Unless the Lord builds the house, those who build it labor in vain.”

— Psalm 127:1