在前面 21 天的探索中，我們從發現 System Prompt 統一管理的需求，到建立模組化架構，再到實現動態調整機制。這個過程中，我們逐漸意識到手動管理多個平台（Claude Code、Cursor）的 System Prompt 配置存在諸多挑戰：檔案同步、版本控制、模組組合的複雜性等。

正當我們思考如何更優雅地解決這些問題時，開源社群中出現了一些專門解決 System Prompt 統一管理的工具。經過研究和測試，我們發現了幾個特別值得關注的解決方案：dotagent、ruler 等。這些工具不僅解決了我們在實踐中遇到的痛點，更提供了超越我們設想的管理能力。

從今天開始，我們將深入探討這些工具如何革命性地改變 System Prompt 的管理方式，讓我們的模組化架構發揮更大的價值。

一、dotagent 專案概述

johnlindquist/dotagent 是一個「Universal AI agent configuration parser and converter」，專門為 AI 開發工具設計的 System Prompt 管理解決方案。與我們前面建立的模組化架構理念不謀而合，dotagent 提供了一套完整的 .agent 目錄管理機制，可以統一管理 Claude Code、VS Code Copilot、Cursor、Cline、Windsurf、Zed、Amazon Q Developer 等多種 AI 開發工具的配置。

1.1 核心設計理念

dotagent 的設計哲學基於幾個重要原則：

統一配置格式：使用 .agent/ 目錄結構，包含 .md 檔案（Markdown 配合 YAML 前置資料）來組織規則，支援巢狀資料夾，不再需要分別維護 .cursorrules、CLAUDE.md 等不同格式的檔案。

自動平台適配：dotagent 可以自動將 .agent 檔案轉換為不同平台所需的格式，實現一份配置多平台使用。

多層級管理：支援巢狀資料夾結構進行更好的組織管理，實現精確的配置控制。

1.2 支援的工具與格式

dotagent 支援的工具範圍相當廣泛：

二、dotagent 的檔案結構與語法

2.1 基本 .agent 檔案結構

dotagent 使用 Markdown 配合 YAML 前置資料的格式：

---
id: core-style
title: Core Style Guidelines
alwaysApply: true
priority: high
---

## Core Style Guidelines

1. Use **Bazel** for Java builds
2. JavaScript: double quotes, tabs for indentation  
3. All async functions must handle errors

2.2 YAML 前置資料的關鍵屬性

根據 GitHub 文檔，dotagent 支援的 YAML 前置資料包括：

• id: 配置檔案的唯一識別
• title: 規則的標題描述
• alwaysApply: 是否總是套用此規則
• priority: 優先級（high/medium/low）
• scope: 適用範圍（如特定目錄路徑）
• manual: 是否需要手動觸發
• private: 是否為私有規則

實際範例：

---
id: api-safety
title: API Safety Rules
scope: src/api/**
manual: true
---

## API Safety Rules

- Never log PII
- Validate all inputs with zod
- Rate limit all endpoints

2.3 巢狀資料夾支援

dotagent 支援巢狀資料夾結構，例如 .agent/frontend/components.md：

---
id: frontend/components
title: Component Guidelines
scope: src/components/**
---

## Component Guidelines

- Use functional components with hooks
- Follow atomic design principles
- Include unit tests for all components

三、dotagent 的安裝與基本使用

3.1 安裝方式

dotagent 支援透過 npm 或 pnpm 進行全域安裝：

npm install -g dotagent
# 或
pnpm add -g dotagent

3.2 基本命令操作

匯入現有配置：

# 從當前目錄匯入（建立 .agent/ 目錄）
dotagent import .

# 從特定路徑匯入
dotagent import /path/to/repo

# 預覽而不實際執行變更
dotagent import . --dry-run

匯出到不同格式：

# 互動式匯出（顯示選單選擇格式）
dotagent export

# 匯出到特定格式（非互動式）
dotagent export --format copilot

# 匯出到多種格式（非互動式）
dotagent export --formats copilot,claude,cursor

# 匯出所有格式
dotagent export --formats all

3.3 命令列參數說明

dotagent 提供豐富的命令列參數：

四、私有規則管理

4.1 私有規則的概念

dotagent 支援私有/本地規則，這些規則會自動從匯出和版本控制中排除。這對以下情況非常有用：

• 不應與團隊分享的個人偏好
• 客戶特定需求
• 臨時實驗性規則
• 敏感資訊或內部流程

4.2 私有規則的識別方式

私有規則可透過以下方式識別：

• 檔案名後綴：*.local.md（例如 api-keys.local.md）
• 目錄：位於 /private/ 子目錄中的檔案
• 前置資料：在 YAML 前置資料中設定 private: true

範例：

<!-- .agent/team-rules.md (PUBLIC) -->
---
id: team-rules
---
# Team Standards
Shared team guidelines

<!-- .agent/my-preferences.local.md (PRIVATE) -->
---
id: my-preferences
---
# My Personal Preferences
These won't be exported

<!-- .agent/private/client-specific.md (PRIVATE) -->
---
id: client-rules
---
# Client-Specific Rules
Confidential requirements

4.3 .gitignore 自動管理

當執行 dotagent export 時，它會自動更新 .gitignore 檔案，加入私有檔案的忽略模式：

# Added by dotagent: ignore private AI rule files
.agent/**/*.local.md
.agent/private/**
.github/copilot-instructions.local.md
.cursor/rules/**/*.local.mdc
.clinerules.local
.windsurfrules.local
.rules.local
CLAUDE.local.md
GEMINI.local.md

五、實際應用場景

5.1 團隊基礎規範統一

建立團隊統一的基礎規範：

<!-- .agent/core-style.md -->
---
id: core-style
title: Core Style Guidelines
alwaysApply: true
priority: high
---

## Core Style Guidelines

1. Use **Bazel** for Java builds
2. JavaScript: double quotes, tabs for indentation
3. All async functions must handle errors

## 基本原則
- 使用英文命名變數和函數
- 遵循語義化命名原則  
- 程式碼必須有適當的註釋
- 錯誤處理不可忽略

## 通用約束
- 避免硬編碼的魔術數字
- 使用一致的縮排（2 空格）
- 函數長度不超過 50 行

5.2 專案特定配置

針對特定專案或技術棧的配置：

<!-- .agent/frontend/react-components.md -->
---
id: frontend/components
title: React Component Guidelines
scope: src/components/**
priority: medium
---

## React 元件開發規範

### 函數式元件優先
- 使用函數式元件配合 Hooks
- 避免使用類別元件

### 型別安全
- Props 介面必須明確定義
- 事件處理函數的型別要正確
- 使用 `React.FC` 或明確的回傳型別

### 測試要求  
- 每個元件都必須有對應的測試檔案
- 使用 React Testing Library 進行測試
- 測試覆蓋率不低於 80%

5.3 與模組化架構的結合

dotagent 完美契合我們前面建立的模組化理念：

.agent/
├── base/
│   ├── naming.md           # 基礎命名規範
│   └── style.md            # 基礎程式碼風格
├── development/
│   ├── typescript.md       # TypeScript 特定規範
│   └── testing.md          # 測試相關規範
├── emergency/
│   └── quick-fix.md        # 緊急修復模式
└── private/
    └── personal-prefs.md   # 個人偏好（不會被匯出）

六、dotagent 相較於手動管理的優勢

6.1 提升團隊協作效率

自動化匯入匯出：

# 從現有專案快速建立 .agent 結構
dotagent import .

# 一鍵匯出到所有支援的平台
dotagent export --formats all

預覽功能降低風險：

# 安全的預覽模式，避免意外覆寫
dotagent export --dry-run

6.2 私有規則管理

相比手動管理，dotagent 的私有規則功能解決了團隊協作中的敏感資訊問題：

• 自動排除：私有規則不會意外被提交到版本控制
• 彈性配置：團隊成員可以保有個人偏好而不影響團隊標準
• 安全性：客戶特定或敏感配置得到保護