iT邦幫忙

2025 iThome 鐵人賽

DAY 2
0
生成式 AI

30 天與 AI 同事打造系統的求生實錄系列 第 2

【Day 2】我在想的,AI 懂嗎?先來對焦一下軟體核心架構與技術棧

  • 分享至 

  • xImage
  •  

今天是鐵人挑戰第二天,今天主要是程式撰寫開始前準備,我會依序講解我的步驟。

第一步我會先準備第一天提到的 mgalpert 分享的 AI 角色提示詞 ,使用git工具 git clone https://github.com/contains-studio/agents.git 將資料下載到資料夾。


第二步我會這個專案的資料夾開啟命令提示字元(CMD),使用gemini -m gemini-2.5-flash -c -y 指令去啟動gemini cli,參數意思為:

  • -m, --model:模型選擇
    指定要使用的模型,例如 "gemini-2.5-pro"。
  • -c, --checkpointing:啟用版本檢查點
    開啟後,會對檔案編輯進行版本儲存(checkpointing)。
  • -y, --yolo:YOLO 模式
    自動接受所有操作,無需人工確認("You Only Live Once" 模式)。

第三步我會請AI準備三個檔案,AI_CONTEXT.md 、 README.md 與 軟體核心架構規劃.md,來確保AI同事在撰寫時不會偏離主軸忘記原本要做什麼。

我給AI的指令:

@agents/engineering/ai-engineer.md 我現在想跟你合作建構一個專案管理系統,不過我想先請你產生出三個檔案,1.ai_context.md:主要讓AI知道規劃跟進度,讓你能掌握專案現況,避免做出不符合業務邏輯的功能。2.readme.md:裡面主要提供給人類看的資訊,包含技術棧、架構、開發日誌等人類開發者會需要的內容。3.軟體核心架構規劃.md:這個主要是包含軟體整體架構與全局規劃。

第四步有了基礎的檔案後,我會請AI透過問答的方式,讓我跟AI同事對專案管理系統有共識。
我給AI的指令:

接下來採用一問一答的方式,問我問題來釐清軟體功能。

AI就會開始針對相關內容跟你進行釐清跟核對,期間你也可以隨時補充跟請他給選項跟建議你回答。
功能需求總覽如下:

  • 核心使用者:小型團隊。
  • 痛點與解決方案:
    • 專案進度共識:即時更新的進度條,顯示任務詳細資訊。
    • 自我任務進度提醒:應用程式內通知和電子郵件通知;每週整合提醒、緊急任務截止前三天提醒、任務逾期立即提醒。
    • 個人創意收集:團隊共用靈感牆和個人筆記功能;創意可透過專案標籤關聯或作為通用創意;方便快速輸入。
    • 全局掌握:專案儀表板(顯示專案完成百分比與各任務進度)、甘特圖(顯示各任務期限)、Google 行事曆聯動。
  • AI 服務:
    • 智慧任務分配建議:未來計畫,暫不實作。
    • 進度預測與風險預警:預測任務是否按時完成、專案是否延期;透過 Gemini API呼叫生成詳細風險分析報告,並透過 Google Mail API 提醒相關成員。
    • 自動化報告生成:每月一次,可手動觸發生成現況報告,報告可選擇與團隊分享;報告需包含專案總體進度百分比、任務狀態分佈、任務逾期情況、任務完成效率、團隊成員工作量與負載、風險與問題追蹤、里程碑達成情況、資源使用情況、歷史趨勢分析等指標。
    • 智慧搜尋與資訊檢索:僅實作創意的文字搜尋和標籤分類。
    • 自然語言介面 (NLI):不實作。

由於我對整理的功能需求不太確定,我拿出studio-producer.md的提示詞去詢問功能建議
我給AI的指令:

@agents/project-management/studio-producer.md 請以你的角度,假如有一套為專案管理設計的程式,除了上面那些敘述,還可能需要哪些功能,請列點出來

讓我驚喜的是,他給出了很多我原本沒設想的過的情況跟需求,下面是整合後的新功能需求總覽

專案管理系統 (TaskWhisker) 功能需求總覽
目標使用者:小型團隊

一、核心專案管理功能

  1. 專案進度共識與追蹤
    • 即時進度條:顯示專案和任務的即時進度百分比。
    • 任務詳細資訊:在進度條或相關介面中,顯示其他團隊成員的任務進度細節。
    • 任務依賴關係管理:
      • 設定任務間的「前置任務」/「後續任務」關係。
      • 甘特圖上視覺化顯示依賴關係。
      • 前置任務延遲時,自動調整後續任務排程。
    • 燃盡圖 (Burndown Chart) / 燃起圖 (Burnup Chart):視覺化顯示專案或衝刺的剩餘工作量和進度趨勢。
    • 甘特圖:顯示各任務期限,幫助掌握全局。
    • 專案儀表板:顯示專案完成百分比與各任務進度概覽。
  2. 任務管理
    • 子任務與檢查清單:支援多層次子任務或簡單檢查清單,細緻分解工作。
    • 任務標籤 (Tags) 與分類:可自定義標籤(如 Bug, Feature, Urgent, Design, Backend)進行篩選和組織。
    • 任務歷史記錄:追蹤任務的狀態變更、負責人變更、評論等所有歷史操作。
    • 任務評論與附件:每個任務具備評論區供討論,並支援上傳文件、圖片、連結。
    • 客製化工作流程:允許團隊自定義任務的狀態流程(例如:待辦 -> 設計中 -> 開發中 -> 測試中 -> 已完成)。
  3. 個人任務與排程
    • 自我任務進度提醒:
      • 應用程式內通知。
      • 電子郵件通知。
      • 每週一次的整合提醒。
      • 緊急任務在截止日期前三天提醒。
      • 任務逾期立即提醒。
    • 通知偏好設定:使用者可自定義接收通知的方式和頻率。
    • Google 行事曆聯動:個人可將任務排程同步至 Google 行事曆。
  4. 個人創意與知識管理
    • 團隊共用靈感牆:供團隊成員分享和瀏覽創意。
    • 個人筆記功能:供使用者記錄私人創意和想法。
    • 創意關聯性:創意可透過專案標籤與特定專案關聯,也可作為通用創意。
    • 快速輸入:提供方便快捷的創意輸入方式。
    • 智慧搜尋與資訊檢索:僅實作創意的文字搜尋和標籤 (tag) 分類。

二、AI 輔助功能

  1. 進度預測與風險預警
    • 預測內容:預測任務是否會按時完成、專案是否會延期。
    • 預警方式:
      • 當預測到風險時,透過 Gemini API 呼叫生成詳細的風險分析報告。
      • 透過 Google Mail API 提醒相關成員。
  2. 自動化報告生成
    • 生成頻率:每月一次,可手動觸發生成當前現況報告。
    • 分享功能:生成後的報告可選擇與團隊分享。
    • 報告內容:包含專案總體進度百分比、任務狀態分佈、任務逾期情況、任務完成效率、團隊成員工作量與負載、風險與問題追蹤、里程碑達成情況、資源使用情況、歷史趨勢分析等指標。
    • 自定義報告:允許使用者根據需求自定義報告內容和篩選條件。
    • 時間追蹤 (Time Tracking):允許團隊成員記錄在每個任務上花費的時間,以便進行工時統計和成本分析。

三、通用與管理功能

  1. 團隊協作與權限
    • 團隊成員角色與權限管理:定義不同角色(如專案經理、開發者、設計師),並賦予相應的存取和操作權限。
    • 即時通訊整合:與常用通訊工具(如 Slack, Microsoft Teams)整合,推送重要通知或任務更新。
  2. 文件與知識管理
    • 文件共享與版本控制:提供集中的文件儲存和管理,支援簡單版本控制。
    • 會議記錄與行動項目 (Action Items):記錄會議內容,並將行動項目直接轉化為任務指派。
  3. 系統管理
    • 專案模板:允許建立和使用預設的專案模板,加速新專案啟動。
    • 數據匯出:能夠將專案數據匯出為常見格式(如 CSV, Excel)。

暫不實作的功能:

  • 智慧任務分配建議 (未來計畫)
  • 智慧搜尋與資訊檢索 (除創意相關外)
  • 自然語言介面 (NLI)

這時我發現自己犯了一個錯誤:在第三步產生 AI_CONTEXT.md、README.md 與 軟體核心架構規劃.md 時,當時還沒和 AI 同事充分討論就先生成了這些檔案。結果這些內容充斥著 AI 憑空想像的假設,後續我試圖請他更新時,他又會夾帶原先錯誤的資訊,造成更多混淆,嚴重影響了後續的討論節奏。

為了修正這個問題,我選擇重新開啟命令提示字元以清除先前的對話歷史,並刪除這三個檔案,改為先請他讀取上一階段產出的 功能需求總表.md,再依據這份需求文件重新生成新的三個檔案。

但接著又遇到另一個狀況。由於我的功能需求中包含一些 AI 功能,如果使用原本的指令,他會誤以為 AI_CONTEXT.md 是某種系統依賴檔案,導致產出錯誤。為了解決這個問題,我請教了我的 Debug 小幫手 ChatGPT,請他協助優化生成指令,他給了我一份中英文版本的建議,我發現英文版本的描述更為精確清楚,因此採用了英文版,並順勢請他協助我優化另外兩個檔案的說明內容。

我給AI的指令最終版:

 @agents/engineering/ai-engineer.md 我現在跟你合作建構一個專案管理系統,請根據我的 @功能需求總覽.md 所提到的功能需求去規劃以下三個檔案。1.ai_context.md is a human-readable context file that provides background information, project goals, and progress updates. It is not required for code execution, but is used to help AI agents maintain continuity and avoid generating features that conflict with business logic. Treat it as an external reference to improve contextual understanding across sessions.2.README.md 是提供給人類開發者閱讀的說明文件,內容包含技術選型、系統架構說明、開發日誌等資訊。這些資訊不影響程式執行邏輯,但能幫助人類理解專案設計與進度。AI 在理解專案時也可參考本檔案,但請勿視為執行程式所需的依賴。3.軟體核心架構規劃.md 是一份系統設計層級的藍圖文件,用來描述整體系統架構、功能模組的組成、資料流向與邏輯依賴關係。內容包含各模組的設計思路、資料流動路徑以及元件之間的互動方式,幫助開發者與 AI agent 理解系統的運作邏輯與設計原則。本文件屬於設計層面的參考資料,不包含實作程式碼或執行邏輯,但對於維持架構一致性、避免邏輯衝突至關重要。

建立好基礎的檔案後,我開始去選擇後端要使用的各項技術,由於我本身對Python比較熟,所以我請我的AI同事去以使用Python去建構後端的環境。
我給AI的指令:

@agents/engineering/backend-architect.md 現在,請根據軟體核心需求決定後端相關要使用的技術,以Python為主,剩下的請用一問一答的方式,並在每一個問題下列一些建議,並提供各建議的優缺點 

經過一連串的問答與跟AI同事釐清後,以下是我目前的技術棧

  • 後端 Web 框架:FastAPI
  • 資料庫:PostgreSQL
  • ORM 工具:SQLModel
  • 即時通訊整合 (外部):n8n
  • 文件儲存:初期使用 Google Drive API,未來擴展至 Google Cloud Storage (GCS)
  • AI 服務模組的 Web 框架:FastAPI
  • 即時通訊 (內部):WebSocket
  • 背景任務/排程:Celery
  • 快取:Redis
  • 日誌與監控:Loki + Grafana

最後,我將今天的討論的內容更新到 readme.md 與 ai_context.md 與 軟體核心架構規劃.md 上
我給AI的指令:

請幫我把資訊更新到 @ai_context.md @README.md @軟體核心架構規劃.md 

今天多花了一點時間在跟AI同事討論釐清我想實作的程式,感覺有越來越大的趨勢XD
有些技術我也加入了一點私心,順便玩一下n8n,希望AI同事能穩的住
今天都在討論後端技術,明天應該會以前端部分來作討論。

我花了比較多時間在跟AI做前期討論,主要是之前我都是請AI同事直接上,結果就是常常做到一半發生用的技術不支援我想要的功能,AI就會弄一些奇怪的方式想繞過去,結果就是越改越糟。
這次我想透過鐵人賽去嘗試假如前期充分討論,能不能抑制AI的暴走,讓他能快速又安全的架設一個可以使用的系統~


上一篇
【Day 1】開始AI Coding前,我的計畫
下一篇
【Day 3】為了不重寫前端,我現在就要跟 AI 講清楚
系列文
30 天與 AI 同事打造系統的求生實錄30
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言