福來朗 內部教學

一個小工具,
從規格書到上線

先寫清楚要什麼,照四步做完,再放上公司的 GitHub 和 Cloudflare。

  1. 1規格書先寫清楚要什麼
  2. 2官方四步流程探索、規劃、實作、收尾
  3. 3放在哪裡GitHub、Workers、D1
  4. 4一段指令上線複製、貼上、按兩次同意
1

規格書:先寫清楚要什麼,再叫 AI 做

英文叫 Spec-Driven Development,簡稱 SDD。GitHub 的 Spec Kit、AWS 的 Kiro 都是這個做法。

寫規格書

要做什麼、給誰用、怎樣算做完

AI 照規格做

不是憑它自己猜

拿規格對答案

一條一條對,全部對上才算完成

對不上,就回頭改規格書,不是一直叫 AI 重做
規格書長這樣(範例:樣品申請登記表)
要做什麼
業務用手機填樣品申請,主管在一頁看到全部申請
給誰用
業務填寫,主管查看與核准
怎樣算做完
手機填得完;送出後主管頁看得到;同一筆不會重複

寫不出規格書?讓 Claude 先訪問

官方建議:功能比較大時,先讓 Claude 一題一題問,問完它自己寫成一份 .md 規格書,再開一個新對話照著做。

貼給 Claude Code
想做一個[用一句話描述工具]。
請用 AskUserQuestion 工具詳細訪問:技術做法、畫面、特殊狀況、取捨。
不要問顯而易見的,挖出還沒想到的難處。
問完之後,把完整規格寫成 .md檔 輸出給我。
2

Claude Code 官方公開的四步工作流程

研究和規劃,跟動手做分開。左邊是示意畫面,右邊跟著亮起目前在哪一步。

Claude Code 示意畫面
⏸ plan mode on
  1. 1

    Explore探索

    先讓 Claude 讀懂現有的素材和需求,還不要它動手。按 Shift+Tab 切到計畫模式,它就只會讀不會改。

  2. 2

    Plan規劃

    Claude 寫出行動計畫,人先看過、確認,再放行。

  3. 3

    Implement實作

    照確認過的計畫做,一邊做一邊對照計畫。

  4. 4

    Commit收尾

    回顧、驗收,存成一個版本。

"Letting Claude jump straight to coding can produce code that solves the wrong problem."

官方原話:讓 Claude 直接跳去寫程式,可能寫出來的是在解決錯的問題。

小改動(改錯字、改一個名稱)不用走計畫。官方的判斷法:改的內容一句話講得完,就直接叫它做。

出處:Claude Code 官方文件 Best Practices
code.claude.com/docs/en/best-practices

3

做出來之後,要放在哪裡?

工具做好時只在自己的電腦裡。要讓同事打得開、資料留得住,要送到兩個地方。

自己電腦的資料夾

Claude Code 做好的工具,一開始在這裡

版本控管 GitHub

程式的存檔點。改壞了,可以回到上一個版本。放在公司的 ecohukurou 組織,一律私有。

託管平台 Cloudflare Workers

讓工具有網址,全世界都打得開。

資料庫 Cloudflare D1

存資料的地方,像樣品申請名單。

金鑰要放對地方

金鑰是程式呼叫 AI 或其他服務用的通行證,等於密碼。放法分三處:

  1. 本機測試時寫在資料夾裡的 .dev.vars 檔,這個檔會被排除,不會推上 GitHub
  2. 上線時跑 npx wrangler secret put 金鑰名稱,貼上金鑰,由 Cloudflare 加密保管
  3. 程式裡用 env.金鑰名稱 讀取,程式碼裡只出現名稱,不出現金鑰本身

最省事的做法:直接跟 Claude Code 說「這把金鑰用 wrangler secret 存」。

4

一段指令,把工具送上線

工具做好之後,照下面兩步走。全程由 Claude Code 用指令完成,不需要自己開網頁點設定。

  1. 複製下面整段,貼上送出它會先確認登入,再問工具的英文名稱,例如 sample-request。
  2. 瀏覽器跳出來時按同意GitHub 一次、Cloudflare 一次,只有第一次會問。
上線指令,貼給 Claude Code
請把[剛剛做的工具名稱]上公司的 GitHub,並部署到公司的 Cloudflare Workers。

規則:
- 全程只用命令列工具(git、gh、npx wrangler、winget),不要用瀏覽器自動操作,也不要叫人去網頁後台點設定。
- 只有「GitHub 登入」和「Cloudflare 登入」這兩步要本人在瀏覽器按同意。遇到時停下來,用白話說明要按什麼,等回覆再繼續。
- 每做完一步,用一句白話回報。出錯時先說發生什麼事、打算怎麼處理,不要自己繞過去。
- 公司帳號裡已經有別人的工具在跑。任何會覆蓋、刪除既有 Worker、倉庫或資料庫的動作一律不准做。

步驟:
1. 檢查環境:node -v 要 22 以上,gh 和 git 要存在。缺的用 winget 安裝(Node.js:OpenJS.NodeJS.LTS;GitHub CLI:GitHub.cli),裝完提醒關掉終端機、重開 Claude Code 再貼一次這段。
2. 登入 GitHub:跑 gh auth status,沒登入就跑 gh auth login(選 GitHub.com、HTTPS、Login with a web browser)。
3. 登入 Cloudflare:跑 npx wrangler whoami,沒登入就跑 npx wrangler login。在帳號清單裡找名稱就是 ecohukurou 的那一個(不分大小寫,名稱要完全一樣,只是包含這幾個字的不算),它就是公司帳號,記下它的 Account ID。找不到、或找到不只一個,就停下來回報,不准自己挑。
4. 取名:問一個英文名稱(小寫英文、數字、連字號,例如 sample-request)。GitHub 倉庫和 Worker 都用這個名字。
5. 建立 wrangler.jsonc:
   - name:這個名稱
   - account_id:第 3 步記下的公司 Account ID(寫死,避免部署到個人帳號)
   - compatibility_date:今天的日期
   - assets.directory:放網頁檔案的資料夾。工具只有網頁檔的話,把它們搬進 public 資料夾再指向 public
   - 工具有後端程式時才加 main,指向後端程式的檔案
6. 確認名字沒人用過,兩個都要查:
   - 跑 npx wrangler deployments list。有列出任何部署紀錄,代表公司帳號裡已經有同名的 Worker,部署會蓋掉別人的工具。回報「這個名字有人用了」,回到第 4 步換名字。出現「does not exist」才代表可以用。
   - 跑 gh repo view ecohukurou/<名稱>。查得到就代表倉庫名稱被用了,一樣回到第 4 步。
7. 整理資料夾:建立 .gitignore,至少排除 node_modules、.env*、.dev.vars*、.wrangler。掃一遍所有檔案,發現金鑰或密碼寫在程式碼裡就停下來回報,不准推上去;金鑰改用 npx wrangler secret put 存。
8. 推上 GitHub:git init、加入所有檔案、commit,然後執行:
   gh repo create ecohukurou/<名稱> --private --source=. --push
   只准推到 ecohukurou 組織,不准推到個人帳號,不准設成公開。
9. 只有工具需要存資料時才做這步:
   npx wrangler d1 create <名稱>-db
   把它給的 d1_databases 設定寫進 wrangler.jsonc,建資料表時用 npx wrangler d1 execute <名稱>-db --remote --file=schema.sql(一定要加 --remote,不加只會建在本機)。
   公司帳號的資料庫有數量上限,不需要存資料就不要建。
10. 部署:跑 npx wrangler deploy。如果它問要不要設定 workers.dev 子網域,停下來回報,不要自己取名。
11. 驗收:用 curl 打開部署後的網址,確認回應是 200,而且內容是這個工具。然後把所有變更 commit,再 git push。
12. 最後回報三行:工具網址、GitHub 倉庫網址、以後改版只要說「推上 GitHub 並重新部署」。

拿到一個工具網址
結尾是 workers.dev,手機也打得開。

GitHub 多一個私有倉庫
在 ecohukurou 組織底下,名稱跟工具一樣。

之後改版只要一句話
對 Claude Code 說「推上 GitHub 並重新部署」。

撞名或出錯會先停下來
名字跟公司裡既有的工具一樣時,會要求換一個,不會蓋掉別人的工具。