昨天把 npm run check 接到 GitHub Actions，現在每次更新 Pull Request，GitHub 都能自動檢查測試、Type Check 與 build。

不過，即使程式和 CI 都正常，新使用者打開 repository 時，第一個看到的通常不是程式碼，而是 README。

如果 README 寫了不存在的指令、尚未完成的功能，或漏掉必要的環境需求，使用者仍然會卡在第一步。

今天要請 Codex 根據 Issue Tracker 的實際內容更新 README，而且每一項說明都必須能在 repository 裡找到依據。

README 也是產品的一部分

README 不只是專案介紹，它也是使用者第一次操作專案時的說明書。

至少應該回答這些問題：

• 這個專案解決什麼問題？
• 目前真的有哪些功能？
• 執行前需要什麼環境？
• 如何安裝與啟動？
• 如何執行完整檢查？
• 資料如何保存？
• 目前有哪些限制？

其中任何一項寫錯，都可能比完全沒寫更麻煩，因為看起來合理的錯誤文件很容易讓人相信。

AI 為什麼容易寫出假文件？

如果只輸入：

幫我把 README 寫完整一點。

Codex 可能會根據常見專案格式，自動補上看似合理的內容，例如：

• repository 裡不存在的 npm run lint
• 專案沒有使用的環境變數
• 還沒完成的登入、資料庫或部署功能
• 沒有證據支持的 Node.js 版本
• 實際不存在的資料夾結構

這些內容不一定是故意亂寫，而是 Prompt 沒有限制資訊來源。

因此今天不是請 Codex「想一份 README」，而是請它「從 repository 整理一份 README」。

先找證據，再寫說明

不同內容應該回到不同檔案確認：

例如昨天的 workflow 使用 npm run check，而 package.json 也真的有這個 script，README 才能把它寫成提交前的完整檢查指令。

如果 repository 沒有 .env.example，程式也沒有讀取環境變數，就不應該自行增加一段環境變數設定教學。

今天使用的 Prompt

我會在 Issue Tracker repository 開啟新的 Codex 任務，輸入：

請根據目前 Issue Tracker repository 的實際內容更新 README.md，讓第一次接觸專案的人可以正確安裝、啟動、操作與驗證。

請先閱讀：
- package.json 與 package-lock.json
- README.md
- AGENTS.md
- `.github/workflows/ci.yml`
- TypeScript、Vite 與測試設定
- src/ 內的實際功能
- 現有測試
- repository 的實際目錄結構

先列出你能從上述檔案確認的事實，以及目前無法確認的資訊，再開始修改。

請將 README 整理成容易閱讀的文件，內容包含：
1. 專案名稱與用途
2. 目前已完成的功能
3. 使用的主要技術
4. 執行專案需要的環境
5. 從安裝相依套件到啟動開發伺服器的步驟
6. `npm test`、`npm run build` 與 `npm run check` 的用途
7. 簡短且符合現況的專案結構
8. 能從程式碼證實的資料保存方式與限制
9. GitHub Actions 會執行的檢查

限制：
- 只寫能從 repository 證實的內容
- 不新增程式目前沒有的功能、指令、環境變數或部署方式
- 不把規劃中的功能寫成已完成功能
- 不推測無法證實的 Node.js 最低版本
- 不為了配合 README 而修改產品程式、測試、設定或套件
- 專案結構只保留新使用者需要理解的部分，不要列出每一個檔案
- 若資訊不足，請在完成回報中列為待確認，不要用猜測補進 README

修改後請實際驗證：
1. README 中提到的每個 npm script 都存在於 package.json
2. 安裝與啟動步驟符合目前專案
3. 執行 `npm run check`
4. 功能說明能在程式碼、測試或實際畫面中找到依據
5. README 沒有寫入 repository 中不存在的設定

完成後請回報：
- 修改了哪些 README 區塊
- 每項主要內容的依據檔案
- 實際執行的驗證與結果
- 仍然無法從 repository 確認的資訊
- 除 README.md 外是否有其他檔案改變
- 目前 Git 狀態

這段 prompt 的回覆和執行

這是我的 repo，在裡面的 commit 找到 "update readme" 就是這篇文章寫完時的狀態。

今日小結

今天讓 Codex 從 package.json、程式碼、測試與 CI workflow 整理 README，並要求每項說明都能回到 repository 找到依據。