The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary.
"無一席話總結"
Top 5 Insights
---
tags: [Prompt工程, AI輔助編程, Agent, 邊界框架, 工作流]
date: 2026-06-16
read: false
source: "2026-06-16T094222+0800-The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary..md"
original_title: "The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary."
---
# The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary.
## 1. 核心概念與 XRay 結構
- 核心概念：在 AI 輔助編程（Agent）中，優化產出品質的關鍵不在於撰寫更巧妙的提示詞（Prompt），而是為 AI 設定明確的「工作邊界（Boundary）」，以此限制其行為沙盒，確保修改結果安全、可控且便於人類審查。
- XRay 結構解析：
- **現狀痛點**：給予 AI 過於開放的任務（如「讓程式碼更乾淨」）會導致其越權修改無關檔案、破壞現有架構，產生看似合理但難以驗證的大型 Diff。
- **核心主張**：提示詞是在「指派工作」，而邊界是在「定義工作區域」。必須讓 AI 清楚知道什麼是成功的結果、什麼是危險的行為，以及何時該停下。
- **四大邊界維度（The Four Boundaries）**：
- 檔案邊界（File Boundary）：明確指定允許編輯的資料夾與絕對禁止觸碰的目標（如共用合約、自動生成檔案、CI 配置）。
- 行為邊界（Behavior Boundary）：定義必須維持不變的系統特徵（如不改變公開 API 簽名、維持既有請求與回應結構）。
- 驗證邊界（Validation Boundary）：規範必須執行的證明程序（如指定需通過的單元測試指令）。
- 停止邊界（Stop Boundary）：設定自動煞車機制（如當需修改超過三個檔案時，必須停止並先提出計畫）。
- **高風險防禦機制（Plan-First Rule）**：處理驗證、支付、資料庫遷移等核心模組時，強制執行「先診斷後執行」的原則，在修改前必須先輸出預期修改清單並等待人類批准。
- **基礎架構化**：將邊界規則從單次的提示詞，下沉至程式碼庫級別的系統配置（如 `.github/copilot-instructions.md` 或 `AGENTS.md`），將隱性團隊知識轉化為 AI 的標準操作手冊。
## 2. 架構深潛 (Architectural Deep Dive)
- **Agent 介面的擴展與風險**：隨著 AI 從單純的文字補全進化為具備工具使用能力的 Agent，其互動介面已超越對話框，延伸至檔案讀取、指令執行與分支建立。若不施加嚴格約束，模型在尋求最佳解時，極易透過修改全域合約來解決局部問題。邊界框架本質上是為 Agent 的行動能力施加「最小權限原則（Principle of Least Privilege）」。
- **可審查性（Reviewability）優於自動化程度**：導入嚴格的邊界會增加開發流程的摩擦力——AI 會頻繁暫停、拒絕修改某些檔案或要求計畫審查。然而，這種效率上的妥協是必要的。在生產環境中，將修改的「爆炸半徑（Blast Radius）」控制在開發者認知負荷範圍內，防止難以察覺的架構層次破壞，其工程價值遠高於一次性的大規模自動重構。
- **決策與執行的狀態解耦**：AI 編程災難多源於模型過早猜測設計意圖並開始改變程式碼狀態（Mutate state）。「Plan-First Rule」在架構上強行切斷了推論與執行的耦合，迫使模型將隱含的規劃過程外顯化為可觀測的計畫。這種機制避免了模型因過早修改而陷入路徑依賴（Path dependence）。
- **權限控制的工程落地**：文章提到了 Claude Code 的權限控制（如編輯白名單/黑名單、讀取拒絕規則、沙盒檔案系統控制）以及 GitHub Copilot 的 Repository 級別指令。這代表著邊界管理正在從「Prompt Engineering」演進為「Configuration as Code」，未來的 AI 專案必須將 Agent 權限範圍直接編碼於 Repo 的基礎架構中，避免 AI 重複性地破壞既定的架構邊界。
---
tags: [實戰教學, Agent架構, AI工程, 開發工具]
date: 2026-06-16
read: false
source: "2026-06-16T093828+0800-AI Agents. What they are and how to Build Your Own Step by Step..md"
original_title: "AI Agents. What they are and how to Build Your Own Step by Step."
---
# AI Agents. What they are and how to Build Your Own Step by Step.
原始來源與檔名：2026-06-16T093828+0800-AI Agents. What they are and how to Build Your Own Step by Step..md
---
## NAPKIN | 餐巾纸
### 餐巾纸公式
> Agent = LLM + Tools + Memory + Loop
_代理不只是一個語言模型，它是模型加上可呼叫的外部工具、跨任務的持久記憶，以及直到任務完成才停止的執行迴圈。_
### 一句话
> AI 代理不是單一的分類而是一個光譜，只要結合 Claude Code 與 Telegram，任何人都能在 20 分鐘內用自然語言打造出具備外部工具與記憶功能的自動化個人助理。
### 餐巾纸草图
```text
[ 用戶請求 ] --> [ Agent Loop ] <====> [ Memory / Context ]
|
v
[ 決策與規劃 (LLM) ]
/ | \
v v v
[ Search ] [ File ] [ API ]
\ | /
\ v /
[ 執行結果回饋 ] ----> [ 任務完成? ] --> [ 輸出結果 ]
```
## ROUND 1: SKELETON | 骨架掃描
**"這本書在說什麼"**
* **核心問題**: 什麼是真正的 AI Agent，以及普通人如何快速建立自己的 Agent？
* **核心答案**: Agent 是具備工具、記憶和執行迴圈的 LLM；透過 Claude Code 與 VPS，只需自然語言即可快速部署專屬的 Telegram 代理機器人。
* **論證結構**: 案例型與實操型結合（先定義光譜，再提供具體程式碼 Prompt 範本與佈署步驟）。
### 章節骨架
1. **定義光譜**: Agent 從單純對話到全自動化。
2. **常見類型**: 研究、寫作、程式、商業與個人助理。
3. **環境準備**: API 金鑰、Telegram Token 與 VPS 伺服器。
4. **初始化建置**: 利用 Claude Code 透過 Prompt 自動生成 Python 程式碼並部署。
5. **擴充技能**: 透過對話新增網路搜尋、儲存筆記、用戶限制等能力。
6. **解決失憶**: 使用 Checkpoint 與 Rolling Summary 解決長文脈絡遺失問題。
## ROUND 2: DISSECTION | 血肉解剖
**"憑什麼這麼說"**
### 論證鏈
```text
單純的 LLM 無法自主執行任務 --> 賦予 LLM 工具呼叫、記憶保留與自動迴圈能力即可成為 Agent --> Claude Code 擅長根據自然語言指令生成並修改系統程式碼 --> 結合 Python 的 Telegram 函式庫與 VPS，即可建立專屬個人的 Agent
```
### 關鍵證據
1. **具備現成工具的生態系**: 使用 Claude API (Sonnet 4.6)、Tavily API 進行網路搜尋，證明外部工具的容易整合。
2. **Claude Code 的程式生成能力**: 只需提供「Build me a Telegram bot...」的 Prompt，Claude Code 就能自動產出包含 `requirements.txt`、`.env` 模板與 `main` 程式碼在內的完整專案。
3. **記憶留存機制**: 透過系統提示詞（System Prompt）以及讀寫 JSON 檔案的方式，能有效解決 Context Window 溢出問題。
### 隱形假設與邊界
* **隱形假設**:
* 使用者具備基礎的終端機 (Terminal) 操作能力。
* 自然語言提示 (Prompt) 必須足夠精準，Claude Code 才能寫出無 Bug 的程式碼。
* 伺服器 (VPS) 能夠穩定連線至 Telegram API 與 Anthropic API。
* **邊界條件**:
* 當任務過於複雜，超出了 Claude 模型的規劃能力時，迴圈可能會無限卡死或產生錯誤決策。
* 當對話歷史不斷堆疊，即便有摘要機制，最終仍可能面臨 Token 成本過高或細節丟失的問題。
## ROUND 3: SOUL | 靈魂提取
**"還能怎麼用"**
* **作者盲點**: 文章雖然解決了個人 Agent 的構建，但忽略了安全性考量（如 Prompt Injection 攻擊），以及系統錯誤時的自動降級或警報機制。
* **知識連接**:
* 與軟體工程中的「狀態機 (State Machine)」概念高度重合。
* 呼應了 LangChain 或 AutoGen 架構中關於 ReAct (Reasoning and Acting) 的核心設計模式。
* **行動觸發**: 立即租用一台廉價的 VPS (如 DigitalOcean)，並使用文中提供的 Prompt 部署一個追蹤個人任務與每日 API 成本的專屬機器人。
### 跨域映射
* 在 **軟體工程**，這叫 **狀態持久化與插件化架構 (State Persistence & Plugin Architecture)**
* 在 **控制理論**，這叫 **閉環控制系統 (Closed-loop Control System)**
---
# AI Agents. What they are and how to Build Your Own Step by Step. (Architectural Deep Dive)
## 前言/背景
隨著大型語言模型 (LLM) 的普及，「AI Agent」成為業界熱詞，但多數人對其定義仍停留在模糊的「自動做事的 AI」。本文從工程角度切入，精確定義了 Agent 的核心構成（工具、記憶、執行迴圈），並提供了一套不需手動編寫程式碼，完全依賴 Claude Code 與自然語言 Prompt，將 AI 代理整合進 Telegram 並部署於雲端 VPS 的完整實戰架構與流程。
## 章節詳細總結
### 1. Agent 的定義與光譜架構 (The Spectrum: From Chat to Agent)
作者指出，Agent 並非一種非黑即白的分類，而是一個「光譜」。一個完整的 Agent 架構必須具備三個超越傳統聊天機器人 (Chatbot) 的核心元件：
* **工具 (Tools)**：能夠主動呼叫的外部介面，如搜尋引擎、檔案系統操作、程式碼執行環境或外部 API。
* **記憶 (Memory)**：能跨越單一 Session 持久化儲存的上下文狀態，而不僅是單次對話的 Token 視窗。
* **執行迴圈 (Loop)**：這是一個控制流 (Control Flow)，驅動 Agent 持續執行「評估->行動->反饋」的循環，直到滿足任務完成條件。
### 2. 系統架構與基礎設施準備 (What you need before starting)
建置個人專屬的 Agent 不需要龐大的算力，其架構極為輕量：
* **大腦運算層**：透過呼叫 Anthropic 的 Claude API。作者建議個人日常使用 **Sonnet 4.6**（效能與成本的最佳平衡），若要極致省錢可選 Haiku 4.5，高難度推理才使用 Opus 4.8。
* **介面層**：透過 BotFather 申請 Telegram Bot Token，作為與 Agent 互動的使用者介面。
* **執行環境**：一台運行 Linux 的低階 VPS（1 CPU, 1GB RAM, 20GB Storage），部署成本約每月 $4-6 USD。
* **建置工具**：在 VPS 上透過 npm 全域安裝 Claude Code：`npm i -g @anthropic-ai/claude-code`。這將作為自動化寫扣與部署的開發者代理。
### 3. 初始化核心架構與部署 (Building Your First Agent)
本文最核心的技術實踐是利用「自然語言即程式碼 (Natural Language as Code)」。透過向 Claude Code 輸入特定的 Prompt，讓其生成 Python 系統架構：
**基礎機器人架構 Prompt**：
```text
Build me a Telegram bot that uses the Claude API as its brain.
Requirements:
- Language: Python
- Library for Telegram: python-telegram-bot
- Claude model: claude-sonnet-4-6
- The bot receives a message, sends it to Claude API, and returns Claude's response to Telegram
- Maintain conversation history per user — each user has their own context within the session
- Add a /start command that introduces the bot
- Add a /clear command that resets conversation history for that user
Create all necessary files: main bot file, requirements.txt, and a .env file template for API keys.
Do not hardcode any API keys — read them from environment variables.
```
* 架構決策 (Why)*：要求使用 `.env` 是為了避免金鑰外洩的標準安全實踐；使用 `python-telegram-bot` 是因為其具備良好的異步 (Async) 支援；按使用者 ID 隔離 Conversation History 是多租戶 (Multi-tenant) 設計的基礎。
**背景服務部署 Prompt**：
為了確保高可用性 (High Availability)，將 Python 腳本封裝為 Linux `systemd` 服務：
```text
Create a systemd service file so this bot runs automatically on my Linux VPS and restarts if it crashes.
```
* 架構決策 (Why)*：依賴系統層級的進程守護程式，實現 Crash 後的自動重啟 (Auto-recovery)，並確保伺服器重開機時自動掛載服務。
**持久化記憶設計 Prompt**：
```text
Save each user's conversation history to a JSON file on disk after every message. Load it back automatically when the bot starts.
Add a maximum history length — keep only the last 20 messages per user so the context window never gets too long.
```
* 架構決策 (Why)*：記憶體內的變數在進程終止時會遺失。透過寫入磁碟 (JSON 檔案) 達成狀態持久化 (State Persistence)；限制保留 20 則訊息則是簡單的滑動視窗 (Sliding Window) 策略，用以控制 Token 消耗與防止 Context Overflow。
### 4. 擴充技能模組 (Adding Skills)
在核心迴圈建立後，透過模組化 (Modular) 的方式為 Agent 增加能力：
* **Web Search (網路搜尋)**：透過 `Tavily API`，並啟用 Claude 的 `Tool use (Function Calling)` 特性。Agent 能自主決定何時呼叫搜尋 API 獲取外部即時數據。
* **Note Saving (檔案系統 I/O)**：實現持久化外部知識庫，遇到特定關鍵字觸發寫入 `notes.txt` 檔案的 IO 動作。
* **Security (權限隔離)**：將管理員的 Telegram User ID 寫入環境變數 `ALLOWED_USER_ID`，並在路由層攔截未授權的請求，避免 API 資源被惡意消耗。
* **Cost Tracking (成本監控)**：攔截 API Response 中的 Token Usage 數據，累積寫入 `costs.json`，並換算為美金，實現基礎的系統可觀測性 (Observability)。
* **Cron Jobs (排程任務)**：整合 `APScheduler` 實作每日定時任務 (Daily Briefing) 的主動推送 (Push Notification)。
### 5. 解決 Context 遺失的記憶工程 (The Memory Problem Every Agent Has)
長任務會導致 Token 視窗溢位。作者提出了四種「記憶壓縮與文脈恢復」的 Prompt 工程策略：
1. **Checkpoint Prompt**：在暫停前，強制 Agent 輸出當前進度、已作決策、待辦事項與所需文脈。
2. **Memory File Prompt**：規定固定的格式記錄狀態 `STEP COMPLETED`, `KEY DECISIONS`, `CURRENT STATE`, `NEXT STEP`，這等同於在對話中實作了一個簡單的狀態機快照 (State Snapshot)。
3. **Context Recovery Prompt**：在新 Session 開始時注入前述的 Snapshot，讓 Agent 無縫恢復狀態。
4. **Rolling Summary Prompt**：當對話過長時，強制觸發一次摘要：「The conversation is getting long. Compress everything important into a summary...」。這是將 O(N) 的歷史紀錄壓縮成 O(1) 的核心技術。
## 總結與結論
* **Agent 的本質是工程封裝而非單純的演算法突破**：將 LLM 加上 `Function Calling` (工具)、`State Persistence` (記憶) 以及 `Control Loop` (迴圈) 即可打造出實用的自動化代理。
* **自然語言即程式碼 (NL-as-Code) 的開發典範**：利用 Claude Code 作為開發代理，架構師只需定義架構需求 (Requirements)、限制條件 (Constraints) 與非功能性需求 (如環境變數、持久化)，而無需處理底層語法細節。
* **狀態管理與文脈壓縮是 Agent 系統的設計核心**：採用滑動視窗 (Sliding Window)、定期狀態快照 (State Snapshot) 以及滾動摘要 (Rolling Summary) 策略，是解決 LLM Token 上限限制並保持長期上下文連貫性的最佳實踐。
* **微型應用的伺服器無伺服器化 (Serverless) 替代性**：雖然本文使用 VPS 加上 `systemd` 部署，但此類無狀態 (Stateless，依靠外部 JSON 儲存) 的 Webhook 機器人，未來也非常適合遷移至 Cloud Run 或 AWS Lambda 配合 DynamoDB 來達成更佳的雲端原生架構。