iT邦幫忙

2025 iThome 鐵人賽

DAY 6
1
生成式 AI

左手藍圖,右手魔法:DDD 與 Vibe Coding 的開發協奏曲系列 第 6

Day 6: 【文件 #1】專案的靈魂:用 Gemini CLI 生成「專案章程」

  • 分享至 

  • xImage
  •  

安安,我是 ChiYu!

經過了五天的「前置作業」,我們的駕駛艙 (VS Code)、引擎 (Python)、魔法法杖 (Gemini CLI) 全都準備就緒了。是不是已經手癢難耐,準備大展身手了?

別急!還記得我們的核心心法嗎?先有藍圖,再有魔法。

今天,我們就要正式啟動專案,打響「左手藍圖」的第一槍!我們將完全在 VS Code 終端機內,為我們的太空船,設定好最初也最重要的航行座標。我們要來產出整個專案中,位階最高、最重要的一份文件——專案章程 (Project Charter)

Part 1:什麼是「專案章程」?它到底有多重要?

「專案章程」…這名字聽起來好像很厲害、很嚴肅,但你別被它嚇到。

你可以把它想像成這個專案的「出生證明」或「身分證」。它用最精簡的方式,回答了幾個最根本的問題:我們是誰?我們要去哪裡?我們要做什麼?以及,我們「不做」什麼?

在團隊開發中,這份文件至關重要,因為它是:

  • 建立共識的基石:專案最怕的就是「我以為我們是要做A,結果你做的是B」。專案章程是第一份讓所有人(老闆、PM、工程師)都點頭同意的文件,確保大家從第一天起,對專案的想像就是一致的。
  • 正式啟動的號角:在企業裡,一份被簽核的專案章程,代表著這個專案被「正式授權」。對我們來說,完成這份文件,就像是為自己舉辦一個開工儀式,代表我們對這個專案的承諾,從此刻起,它不再只是個空想。
  • 未來決策的北極星:開發過程中,我們肯定會冒出各種新點子。這時候,我們就可以拿出專案章程來檢視:「這個新點子,符合我們的『願景』和『範圍』嗎?」它能幫助我們抵抗「範圍潛變 (Scope Creep)」這個專案的無聲殺手,確保我們能聚焦在核心價值上。

總之,在一頭熱地栽進去開發前,先把這份文件定義清楚,就像開車前先在 Google Maps 設定好目的地。它就是我們後續所有文件的最高指導原則。

Part 2:實戰開始:在終端機中從無到有

接下來,就是見證奇蹟的時刻。我們將把腦中那個非常模糊的想法,透過與 Gemini CLI 的對話,直接在我們的專案中,生成一份專業文件。

魔法的基礎:什麼是提示工程 (Prompt Engineering)?

在我們詠唱第一個咒語之前,我們先來學習「咒語的文法」。與 AI 溝通,是一門藝術,也是一門科學,這就是所謂的「提示工程 (Prompt Engineering)」。

你可以把它想像成你在對一個法力無邊的「許願精靈」下指令。

  • 糟糕的許願:「我想要變有錢!」 -> 精靈可能會給你一張樂透彩券,或是讓你家地下冒出處理起來很麻煩的石油。
  • 優秀的許願:「請在今天下午三點前,將一百萬新台幣,以合法的銀行轉帳方式,存入我指定的銀行帳戶。」

看到了嗎?一個好的 Prompt,就像一個好的許願,它清晰、具體、有邊界、有上下文。這能大幅降低 AI「理解錯誤」或「自由發揮」的機率。

根據業界的最佳實踐(例如 OpenAI 的官方文件),一個高品質的 Prompt 通常包含幾個關鍵要素,而這也正是我們接下來所有咒語的設計核心:

1. 角色扮演 (Role-playing):為 AI 賦予專家身份

這是最重要,也最容易被忽略的一點。在指令的開頭,先告訴 AI 他「是誰」。這會讓模型進入一個特定的知識領域與思考模式,產出的內容會更專業、更貼近你的需求。

  • 不好的指令: 幫我寫一個 Python 函式來驗證電子郵件。
  • 好的指令: 你是一位資深的 Python 開發者,專長是後端開發與資料驗證。請幫我寫一個符合 RFC 5322 標準的 Python 函式來驗證電子郵件...

賦予角色後,AI 會自動調用與該角色相關的知識,例如程式碼風格、使用的函式庫、考慮的邊界情況等。

2. 清晰目標 (Clear Objective):明確定義「完成」的標準

你必須非常清楚地告訴 AI 你想要「什麼」。不要使用模糊的詞語,例如「好一點」、「優化一下」。

  • 不好的指令: 讓這段程式碼跑快一點。
    • 好的指令: 你是一位專注於演算法與效能優化的 C++ 工程師。請分析以下這段 C++ 程式碼,找出效能瓶頸,並在不改變其核心邏輯的前提下,提出三種可以降低時間複雜度的重構建議。請解釋每一種建議的優缺點。

3. 提供上下文 (Provide Context):給予足夠的背景資訊

AI 不知道你的專案背景、程式碼架構或你的最終目的。你提供的上下文越豐富,他給出的答案就越精準。

  • 需要提供的重要上下文包括:
    • 程式語言與框架我正在使用 Next.js 14 與 TypeScript...
    • 相關程式碼:貼上相關的 function、class 或檔案內容。
    • 錯誤訊息:完整貼上終端機的錯誤日誌 (Error Log)。
    • 目標與限制這個函式將會部署在記憶體只有 256MB 的 AWS Lambda 環境中,因此需要特別注意記憶體用量。
    • 專案結構我的專案目錄結構如下,請將新檔案放在 components/auth/ 資料夾中...

4. 設定限制與格式 (Constraints & Formatting):規範輸出,方便使用

告訴 AI 你「不想要」什麼,以及你希望他用什麼「格式」回覆你。這能省去你大量後續整理的時間。

  • 限制 (Constraints)
    • 請不要使用任何第三方函式庫。
    • 程式碼風格必須遵循 PEP 8 規範。
    • 解決方案中不能使用遞迴 (recursion)。
  • 格式 (Formatting)
    • 請用 Markdown 格式回覆。
    • 所有的程式碼區塊都必須明確標示語言,例如 \```python。
    • 請將你的解釋與程式碼範例分開。
    • 請以 JSON 格式輸出結果,key 必須包含 "functionName", "description", "code"。

5. 迭代與追問 (Iteration & Follow-up):像對話一樣逐步深入

不要期望一次就得到完美的答案。把與 AI 的互動看作一場對話。第一次的 Prompt 產出了 70 分的答案,你可以針對不足之處進行追問,逐步將答案優化到 100 分。

  • 範例對話流程
    1. : (給予一個完整的初始 Prompt)
    2. AI: (產生初步的程式碼)
    3. : 這個方案很好,但請加入詳細的註解,解釋每一行的作用。
    4. AI: (加入註解)
    5. : 現在,請為這個函式撰寫三個單元測試案例,使用 pytest 框架,包含一個正常情況、一個邊界情況、跟一個錯誤情況的測試。
    6. AI: (產生測試案例)

現在,讓我們用這個專業的「許願框架」,來詠唱我們的第一個創世咒語。

Step 1:詠唱「創世」咒語,生成第一版草稿

  1. 在 VS Code 的專案根目錄,先手動建立一個 docs 資料夾,我們未來所有的文件都會放在這裡。
  2. 打開終端機,詠唱我們的第一個「文件生成咒語」:

【魔法詠唱:我們的 Prompt】


# 角色 (Role)
你是一位頂尖的產品策略顧問,擁有十年以上成功推出 Web 應用程式的經驗,專長是將模糊的初始概念,轉化為清晰、可執行的專案計畫。你的思考兼具市場洞察力與技術可行性。

# 目標 (Objective)
我的任務是,請你根據我提供的專案初步構想,為我生成一份專業、完整、且具備策略高度的「專案章程 (Project Charter)」。

---

## 專案構想資訊 (Project Idea Details)

* **專案核心想法**:
    `我想做個能幫助使用者追蹤好習慣、記錄每日心情的 Web App。`

* **目標使用者 (Target Audience)**:
    `追求個人成長、希望提升自我覺察能力的年輕上班族與大專院校學生。他們通常對心理學、時間管理有興趣,但生活忙碌,需要一個簡單、無壓力的工具來幫助自己。`

* **要解決的關鍵問題 (Problem to Solve)**:
    `使用者常常感覺自己的情緒起伏不定,卻不清楚背後的原因。同時,他們嘗試建立良好習慣(如運動、冥想),卻因為缺乏持續的正向反饋而難以堅持。現有的工具要嘛功能太過繁雜,要嘛缺乏將「行為」與「感受」連結的洞察。`

* **獨特價值主張 (Unique Value Proposition) (可選)**:
    `我們的核心差異化在於「關聯性洞察」。應用程式會透過簡單的視覺化圖表,主動向使用者揭示他們的特定習慣與心情波動之間的正向或負向關聯,提供個人化的洞察,而不僅僅是數據記錄。`

* **專案暫定名稱 (Working Title) (可選)**:
    `心境軌跡 (MindTrack)`

---

## 你的任務與產出要求 (Your Task & Output Requirements)

1.  **生成文件**: 請將上述的構想資訊,擴寫成一份結構完整的專案章程。
2.  **文件格式**: 必須使用 **Markdown** 格式。
3.  **文件語言**: 繁體中文。
4.  **文件大綱**: 請**嚴格遵從**以下大綱結構,並為每個段落產生具體的內容:
    * **文件標題與版本資訊**: 包含版本號 1.0 與作者(產品策略顧問)。
    * **專案願景 (Project Vision)**: 描繪一個鼓舞人心的未來藍圖,說明這個專案的終極理想。
    * **主要目標 (Goals)**: 列出 2-3 個具體的、可衡量的、有時限的專案目標 (SMART Goals)。
    * **成功衡量指標 (Success Metrics)**: 針對每個目標,提出量化的衡量指標(例如:使用者留存率、活躍使用者數、特定功能使用率)。
    * **專案範圍 (Scope)**: 明確定義「範圍內 (In-Scope)」與「範圍外 (Out-of-Scope)」的事項,幫助團隊聚焦。
    * **核心功能 (Core Features)**: 以項目符號列出構成最小可行性產品 (MVP) 的關鍵功能。
    * **初步假設與風險 (Assumptions & Risks)**: 列出專案成功所依賴的幾個關鍵假設,以及可能遇到的潛在風險。

5.  **直接產出**: 請直接生成完整的 Markdown 文件檔案,命名為[PROJECT_CHARTER.md]後,放置於 @docs 資料夾內。

Step 2:審核、迭代與分析

【重要心法】AI 不是上帝,你才是專案的主人

AI 產出的內容,永遠都只是一份「草稿 (Draft)」。它是一個能力超強的實習生,幫我們完成了 80% 的工作,但最後那 20% 的審核、微調、與最終拍板,絕對要由我們自己來完成。

方法一:用 @ 指令直接修改

打開剛剛生成的 PROJECT_CHARTER.md,你可能覺得「主要目標」寫得不夠好。沒問題,我們直接命令 AI 修改它!

gemini "請你檢視我附加的這份專案章程草稿。我覺得「主要目標 (Goals)」這個章節寫得不夠具體。請你幫我把這個章節,改寫得更符合 SMART 原則,然後輸出修改後的**完整**文件內容。" @docs/PROJECT_CHARTER.md > docs/PROJECT_CHARTER.md

看到了嗎?我們用 @ 讀取舊檔案,下達修改指令,然後用 > 將修改後的新版本,直接覆蓋掉舊檔案!這就是 AI 輔助的「原地重構」!

方法二:直接修改文件

打開剛剛生成的文件,直接針對需要修改的地方修改,修改完成後可以在請AI幫我們順過文件,將文件調整好。

【AI 生成文件範例】

在你與 AI 經過幾輪的迭代優化後,最終你會得到一份高品質的定稿文件,就像下面這樣:

# 專案章程:心境軌跡 (MindTrack)

- **版本**: 1.0
- **作者**: 產品策略顧問

---

## 1. 專案願景 (Project Vision)

我們的願景是,打造一個最直覺、最富有洞察力的個人成長工具。我們相信,真正的自我提升源於深刻的自我覺察。`心境軌跡 (MindTrack)` 將不僅僅是一個紀錄工具,而是每一位使用者專屬的數據分析師,透過揭示個人行為與內在感受之間的微妙聯繫,賦予他們改善生活品質的知識與力量,最終引導使用者走向一個更健康、更快樂、更有意識的生活方式。

## 2. 主要目標 (Goals)

我們將專注於以下幾個關鍵的、可衡量的目標,以確保專案初期的成功:

1.  **產品開發目標**: 在接下來的 **3 個月內**,成功開發並上線具備核心功能的最小可行性產品 (MVP),確保其穩定性與核心價值主張的展現。
2.  **市場驗證目標**: 產品上線後的 **6 個月內**,吸引並累積 **1,000 名活躍使用者**,以驗證產品概念對目標市場(追求個人成長的年輕上班族與學生)的吸引力。
3.  **價值主張驗證目標**: 在上線後的 **6 個月內**,透過數據分析證明「關聯性洞察」功能能有效提升使用者參與度,目標是讓使用此功能的使用者 **28 天留存率**相較於未使用者**提升 20%**。

## 3. 成功衡量指標 (Success Metrics)

為了客觀評估我們是否達成上述目標,我們將追蹤以下關鍵績效指標 (KPIs):

| 主要目標 | 關鍵成功指標 (KPIs) |
| :--- | :--- |
| **1. 產品開發** | - **上線時程**: 專案是否在預算內及時程內(3 個月)完成 MVP 開發並部署。 <br> - **程式錯誤率**: 上線後一個月內的嚴重錯誤 (Critical Bugs) 數量低於 5 個。 |
| **2. 市場驗證** | - **月活躍使用者 (MAU)**: 第 6 個月結束時,MAU 達到或超過 1,000 人。 <br> - **使用者註冊轉換率**: 訪問首頁的使用者中,有 15% 完成註冊。 |
| **3. 價值主張驗證** | - **28 天使用者留存率**: 整體使用者 28 天留存率達到 10% 以上。 <br> - **核心功能採用率**: 至少 60% 的活躍使用者每週至少使用一次「關聯性洞察」圖表功能。 |

## 4. 專案範圍 (Scope)

為了集中資源、快速迭代,我們將嚴格定義本次 MVP 開發的範圍。

#### **範圍內 (In-Scope):**

*   **使用者帳號系統**: 包含註冊、登入、登出及基本的個人資料管理。
*   **每日習慣追蹤**: 使用者可以自定義想要追蹤的每日習慣,並以簡單的「打勾」方式完成記錄。
*   **每日心情記錄**: 提供一個簡單的介面(例如:1-5 分的評分量表),讓使用者快速記錄當日心情。
*   **關聯性洞察視覺化**: 開發一個基礎的視覺化圖表,展示心情分數趨勢與特定習慣完成情況之間的關聯性。
*   **響應式網頁設計 (RWD)**: 確保應用程式在桌面與行動裝置瀏覽器上皆有良好的使用體驗。

#### **範圍外 (Out-of-Scope):**

*   **原生 App 開發 (iOS/Android)**: MVP 階段將專注於 Web App。
*   **社交功能**: 例如好友、分享、排行榜等功能。
*   **複雜目標設定**: 例如設定每週目標、目標依賴性等進階功能。
*   **第三方服務整合**: 例如與行事曆、穿戴式裝置的數據同步。
*   **AI 驅動的預測與建議**: MVP 階段不包含自動化的智慧建議功能。
*   **內容或課程模組**: 不提供冥想引導、文章閱讀等內容。

## 5. 核心功能 (Core Features)

構成最小可行性產品 (MVP) 的具體功能列表如下:

*   **[使用者]** 可以透過 Email 和密碼建立一個新帳號。
*   **[使用者]** 登入後,可以進入個人的主控台頁面。
*   **[使用者]** 可以在主控台上新增、命名想要追蹤的習慣(例如:運動、閱讀、冥想)。
*   **[使用者]** 每天可以針對已建立的習慣,點擊「完成」按鈕進行打卡。
*   **[使用者]** 每天可以使用一個 1 到 5 的評分條來記錄自己的整體心情。
*   **[使用者]** 可以選擇性地為當日心情添加一段簡短的文字註記。
*   **[使用者]** 可以查看一個視覺化圖表,該圖表以時間軸呈現過去 30 天的心情分數曲線,並在圖表上標示出已完成特定習慣的日期,以供對照。

## 6. 初步假設與風險 (Assumptions & Risks)

我們認知到專案的成功建立在以下假設之上,並已識別潛在風險。

#### **主要假設 (Assumptions):**

1.  **使用者意願**: 我們假設目標使用者有足夠的動機,願意為了獲得洞察而持續每日記錄他們的習慣與心情。
2.  **數據價值**: 我們假設透過簡單的數據疊加,確實能產生讓使用者感到「有價值」的關聯性洞察。
3.  **平台選擇**: 我們假設以 Web App 作為起點,足以觸及並服務我們的早期使用者,他們不強烈要求立即擁有原生 App。

#### **潛在風險 (Risks):**

1.  **使用者數據隱私疑慮 (高風險)**: 使用者可能因擔心心情等敏感數據的隱私問題而卻步。
    - **應對策略**: 從第一天起就建立清晰、透明的隱私權政策。在技術上採用端到端加密,並在行銷上強調我們對數據安全的承諾。
2.  **使用者黏著度不足 (高風險)**: 使用者可能在初期因未立即看到價值,或覺得每日記錄過於繁瑣而放棄使用。
    - **應對策略**: 優化使用者體驗,讓記錄過程盡可能無摩擦。透過新手引導,快速展示產品的核心價值。設計溫和的提醒機制 (Email/推播)。
3.  **洞察的有效性不足 (中風險)**: 簡單的關聯性分析可能無法提供真正有意義的洞察,導致使用者失望。
    - **應對策略**: MVP 階段保持圖表簡單直觀,並收集使用者回饋。規劃在後續版本中引入更成熟的統計模型或允許使用者標記影響事件。
4.  **市場競爭 (中風險)**: 市場上已存在功能強大的習慣追蹤器或日記應用。
    - **應對策略**: 專注並強化我們的獨特價值主張——「習慣與心情的關聯性洞察」,並以此作為行銷和產品設計的核心。

當然這邊主要目標列出的時間我們參考即可,這邊的時間是沒有AI輔助,純人工一個人當作SideProject逐步開發出來的時間或許真的就這麼花時間!這邊我就沒有特別調整(懶),我們先將目標放在[最小可行性產品 (MVP)]。可以快速上線即可~

Part 3:將我們的藍圖存檔 (Commit to GitHub)

當你得到一份滿意的「定稿」版本後,是時候將它寫入專案的歷史了。

提交變更 (Commit):

  1. 點擊 VS Code 左側活動列的「原始碼管理」圖示。
  2. docs/PROJECT_CHARTER.md 檔案名旁,點擊「+」號 (Stage Changes)。
  3. 在上方「Message」輸入框中,輸入訊息:docs: Create initial project charter
  4. 點擊「V」打勾按鈕 (Commit)!

推送到雲端 (Push):

  1. 點擊左下角狀態列的「同步變更」按鈕。

現在,去你的 GitHub 倉庫頁面重新整理看看,docs 資料夾跟裡面的 PROJECT_CHARTER.md 是不是已經靜靜地躺在那裡了?

結語:不只是一份文件,更是一份出航許可證!

恭喜!今天,我們完全在終端機內,從一個飄渺的想法,到手握一份專業的專案章程,並在 GitHub 上留下了第一個不可磨滅的印記。我們的太空船,不僅有了目的地,更有了一張正式的「出航許可證」!

有了專案的最高指導原則,下一步,我們就要來深入使用者的世界。明天,我們將繼續扮演產品經理,用 Gemini CLI 產出關鍵的「使用者故事 (User Stories)」與「流程圖」!


上一篇
Day 5: 【工具篇 #3】終端機裡的魔法:什麼是 Vibe Coding 與 Gemini CLI?
下一篇
Day 7: 【文件 #2】使用者的旅程:用 Gemini CLI 描繪「使用者故事」
系列文
左手藍圖,右手魔法:DDD 與 Vibe Coding 的開發協奏曲14
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言