# 在既有專案中使用 OpenSpec

**您無須在剛開始時為整個程式碼庫撰寫文件。您只需為即將變更的部分撰寫規格。** 這是關於在既有專案上採用 OpenSpec 最重要的一點，也是 OpenSpec 專為既有（brownfield）專案設計的原因。

常見的擔憂通常是：「我的應用程式已有 80,000 行程式碼。在 OpenSpec 發揮作用之前，我是否必須為所有程式碼撰寫規格？」不需要。您會討厭那樣做，我們也是。OpenSpec 會隨著每一次變更逐步累積規格。您的第一個變更只記錄它所觸及的切面，下一個變更記錄其觸及的切面，幾個月下來，規格會隨著您實際進行的工作自然完善。

本指南說明如何在第一天就順利起步，而不需要大費周章一蹴可幾。

## 三十秒精華版

```bash
$ cd your-existing-project
$ openspec init          # 新增 openspec/ 與您 AI 工具的指令
```

接著，在您的 AI 聊天室中：

```text
/opsx:explore            # 可選：讓 AI 閱讀您即將修改的區域
/opsx:propose <一項您實際需要的真實、小型變更>
/opsx:apply
/opsx:archive
```

您的規格現在精確描述了該變更所觸及的系統部分，僅此而已。這是完全正確的。您無須再為其餘 80,000 行程式碼煩惱。

## 為何 Delta 優先是關鍵訣竅

OpenSpec 變更是以 **Delta** 形式撰寫的：`ADDED`、`MODIFIED`、`REMOVED`。Delta 描述的是相對於當前行為的變更，而非整個系統。

這正是既有專案工作所需要的。您很少從零開始建構。您是在新增欄位、修復重新導向、縮短逾時時間。Delta 讓您能夠精確指定單一變更，而無需先為其周圍的所有內容撰寫 40 頁的規格。

因此，您的 `openspec/specs/` 目錄並非一開始就是完整齊備的。它從幾乎空白開始並持續累積。每個封存的變更都會將其 Delta 合併進去。`auth/` 的規格只有在您進行了幾次身分驗證相關變更後才會變得詳盡，而這正是您希望它詳盡的時機。

如果您想了解更深入的運作機制，請參閱[概念：Delta 規格](concepts.md#delta-specs)。

## 在真實程式碼庫上的第一個變更

選擇小型且真實的內容。不是玩具專案，不是大規模重寫。而是您本週本來就打算進行的變更。小型的初次變更讓您能以低風險學習工作流程。

**步驟 1：讓 AI 閱讀相關區域。** 在不熟悉或大型的程式碼庫上，這正是 `/opsx:explore` 發揮價值之處。將其指向您即將修改的部分，讓它在提出任何提案之前先釐清運作方式。

```text
You: /opsx:explore

AI:  What would you like to explore?

You: I need to add rate limiting to our public API, but I'm not sure
     how requests currently flow through the middleware.

AI:  Let me trace it... [reads the router, middleware stack, and config]
     Requests hit Express, pass through auth middleware, then your
     controllers. There's no rate-limiting layer today. The cleanest
     insertion point is a middleware right after auth. Want me to scope it?
```

請注意，AI 現在已理解您的實際結構，因此它所撰寫的提案將貼合您的程式碼，而非通用的範本。在大型程式碼庫上，僅這一個習慣就能避免最多的麻煩。請參閱[探索優先](explore.md)。

**步驟 2：提出變更提案。** 提案及其 Delta 規格僅記錄這項變更。

```text
You: /opsx:propose add-api-rate-limiting
```

**步驟 3：建構與封存** 使用 `/opsx:apply` 與 `/opsx:archive`，與任何變更相同。封存後，您就擁有了速率限制行為的真實規格，這源自於您本來就需要的一項變更。

## 想要引導式教學？使用 onboard

如果您希望在自己的程式碼上觀看整個流程並伴隨解說，擴充指令 `/opsx:onboard` 正是為此而設計：它會掃描您的程式碼庫以尋找小型且安全的改善點，然後引導您完成提案、建構與封存，並解釋每個步驟。

首先啟用擴充指令：

```bash
$ openspec config profile      # 選擇 expanded 工作流程
$ openspec update              # 套用至此專案
```

然後在聊天室中輸入：

```text
/opsx:onboard
```

這是在真實專案上最平緩的入門方式，並會為您留下一個可以保留或捨棄的真實（小型）變更。請參閱[指令：`/opsx:onboard`](commands.md#opsxonboard)。

## 「但我已經有需求文件了」

也許您已經有 PRD、SRS、正式規格，甚至是 TLA+ 模型。這很好。您不需要全盤匯入，也不需要丟棄它們。

將既有文件視為**探索的原始素材**，而非要轉換的規格。當您開始一項變更時，貼上或引導 AI 閱讀相關區段，並讓它從中形塑出聚焦的 OpenSpec Delta。Delta 會以 OpenSpec 可測試的需求與情境形式，擷取您目前正在變更的行為。您的原始文件則作為背景資料保留在原地。

真實的原因是：OpenSpec 規格特意以行為優先且範圍侷限於變更。40 頁的 PRD 是具有不同任務的另一種產物。強行進行一次性大量轉換往往會產生龐大且過時、無人信任的規格。讓規格從真實變更中成長，能確保其準確性。

```text
You: /opsx:explore
You: Here's the section of our PRD about checkout. I'm implementing the
     "guest checkout" requirement next.
     [paste the relevant requirement]
AI:  [reads it, asks clarifying questions, then helps scope a change]
You: /opsx:propose add-guest-checkout
```

## 在大型程式碼庫中組織規格

規格存放於 `openspec/specs/` 底下，按**領域（Domain）**分組：符合團隊對系統理解方式的邏輯區域。您不需要預先設計完整的分類法。當您在該區域的第一個變更需要時，再建立領域資料夾即可。

劃分領域的常見方式：

- **依功能區域：** `auth/`、`payments/`、`search/`
- **依元件：** `api/`、`frontend/`、`workers/`
- **依邊界上下文（Bounded Context）：** `ordering/`、`fulfillment/`、`inventory/`

選擇任何能讓新成員理解的方式。您可以稍後再進行微調。請參閱[概念：規格](concepts.md#specs)。

## Monorepo 與跨儲存庫工作

對於 Monorepo，最簡單的模型是在儲存庫根目錄放置一個 `openspec/` 目錄，其中的領域對應至您的套件或服務。這適用於大多數團隊。

如果您的工作確實橫跨**多個儲存庫**（或多個您視為獨立的套件），OpenSpec 提供 Beta 版的 **Stores** 功能：規劃存放於其專屬的獨立儲存庫中，您的任何程式碼儲存庫都可以參照它，因此計畫不需要存放在單一儲存庫的 `openspec/` 資料夾內。這仍處於 Beta 階段，因此請將其指令與狀態視為演進中。請從 [Stores 使用者指南](stores-beta/user-guide.md)開始，以了解心智模型與最小可行路徑。

## 一些中肯的提醒

- **克制回填所有內容的衝動。** 為您未曾修改的程式碼撰寫規格看似很有成效，但通常並非如此。這些規格容易過期，因為沒有任何機制強制它們與現實保持一致。讓真實的變更來驅動您的規格。
- **保持初期變更規模精簡。** 您最初的幾個變更重點在於熟悉節奏與交付。緊湊的範圍能讓循環快速且學習成本低廉。
- **將 `openspec/` 提交至 Git。** 您的規格與封存紀錄應與所描述的程式碼一同納入版本控制。
- **為 AI 提供上下文。** 在具有嚴格慣例的大型程式碼庫上，請填寫 `openspec/config.yaml` 的 `context:`，使每個提案都能遵循您的技術堆疊與模式。請參閱[客製化](customization.md#project-configuration)。

## 下一步

- [探索優先](explore.md) - 在修改程式碼前理解程式碼的關鍵習慣
- [快速入門](getting-started.md) - 完整的第一個變更逐步指南
- [編輯與迭代變更](editing-changes.md) - 隨著理解深入調整變更
- [概念：Delta 規格](concepts.md#delta-specs) - 為何 Delta 能讓既有專案工作保持俐落
- [客製化](customization.md) - 向 OpenSpec 傳達您專案的慣例