用 AI 寫一份專業的 GitHub README：從標題、徽章到讓 README 幫你找到工作

一分鐘重點：GitHub 上的專案沒人看、沒人 star，多半不是程式寫得爛，而是 README 只有一行「我的專案」。README 是別人打開你儲存庫的第一眼，也是招募方判斷你工程素養的樣本。這篇教你先把專案事實整理成清單，再用一段可複製的 Prompt 讓 AI 產出含標題、徽章、安裝、使用範例、貢獻指南、授權的完整骨架，然後你負責當事實查核員：砍掉 AI 腦補的功能、親手實測每一條安裝指令、補上截圖與「這對誰有用」的定位。做對了，這份 README 會在你面試時替你講話。

你一定看過這種畫面：點進一個看起來很厲害的 GitHub 儲存庫，往下滑想知道這東西怎麼用，結果 README 只有一行專案名稱，或者乾脆是 create-react-app 自動產生的那份罐頭說明沒改過。那一刻，不管程式寫得多好，你關掉分頁的機率是九成。

反過來，一份好的 README 能讓一個路過的陌生人在三十秒內判斷：這是什麼、對我有沒有用、我要不要 star、我能不能貢獻。它不只是說明書，它是你專案的門面，更是你工程素養對外的樣本。偏偏寫 README 這件事，多數工程師都討厭——寫程式很爽，寫文件很煩。這正是 AI 最能補位的地方：它幫你把「懶得寫」這個藉口拿掉，把一份空白 README 變成一份結構完整的草稿。但草稿不等於成品，中間那段把關的功夫，才是這篇要教你的重點。

一份好 README 該有的骨架

在叫 AI 之前，你得先知道成品長什麼樣，否則 AI 給你什麼你都收。一份合格的 README，由上到下大致是這幾塊：

• 專案標題與一句話定位：專案叫什麼，以及最重要的——它解決誰的什麼問題。這一句話決定別人要不要繼續往下看。
• 徽章（badges）：授權、build 狀態、版本號、下載數這類一眼可判斷專案健康度的資訊條。
• 示範截圖或 GIF：能用看的就別用讀的，一張圖勝過三段文字。
• 功能特色：條列這個專案能做什麼，挑真正的亮點，不要流水帳。
• 安裝步驟：從零開始把它跑起來要打哪些指令，寫給一個完全沒碰過的人看。
• 使用範例：最基本的用法，最好是可以直接複製貼上就會動的一段程式碼或指令。
• 設定與環境變數：需要哪些 API 金鑰、環境變數、設定檔。
• 貢獻指南：想找人一起做，就要說清楚怎麼參與。
• 授權（License）：這是最多人忘記、卻攸關別人能不能用你程式碼的一塊。
• 致謝與延伸連結：用到的重要套件、靈感來源、相關文件。

不是每個專案都要全上。一個週末寫的小工具，有標題、一句話定位、安裝、使用範例、一張截圖就夠了。貢獻指南、行為準則這些是給預期會有人協作的專案準備的。README 的厚度該配合專案的複雜度，硬塞區塊只會顯得虛。

阿哲的 side project：一行 README 的代價

台北一位後端工程師阿哲，利用下班時間做了一個小工具：把台灣各家銀行的匯率抓下來、算出換匯最划算的一家，做成一個 CLI 指令。程式本身寫得很紮實，還接了快取、處理了 API 逾時重試。他很得意地推上 GitHub，README 只寫了一行：「台灣換匯比價工具」。

三個月過去，star 數是二。他自己都快忘了怎麼跑。後來他在面試一家新創時，把這個專案放進履歷，面試官當場點開 GitHub，滑了兩秒、看到那行孤零零的 README，就問了下一題——那個專案等於沒被看見。

阿哲回家把它重寫了。他先花十分鐘把事實列出來：這工具解決「懶得一家一家查匯率」的痛、用 Node.js 寫、怎麼安裝、跑起來長什麼樣。然後把清單餵給 AI 產出骨架，逐段核對砍掉 AI 幫他腦補的「支援多國貨幣」（他根本沒做），親手在乾淨的機器上照安裝步驟跑一次，補了一張終端機輸出的截圖，最後在開頭寫上：「每天早上幫你在十家台灣銀行裡找出換美金最划算的一家。」

同一份程式碼，換了一份 README。兩週後那個專案的 star 破了三十，還有人開了第一個 issue 問能不能加日圓。更重要的是，下一次面試，面試官滑到那份 README 時停下來多看了幾秒，順著問了他快取跟重試是怎麼設計的——這一次，專案替他講了話。

可直接複製的 Prompt：一次生出 README 骨架

把你整理好的事實填進下面這段 Prompt 的變數佔位，丟給任何一個 AI 助理，就能得到一份結構完整的 README 草稿。關鍵在於：你給的事實愈具體，AI 腦補的空間就愈小。

你是一位資深開源專案維護者，寫過大量被高度 star 的 GitHub README。
請根據我提供的專案事實，產出一份結構完整、語氣專業但不浮誇的 README.md，用 Markdown 格式輸出。

【專案事實】
- 專案名稱：〔專案名稱〕
- 一句話定位（解決誰的什麼問題）：〔解決什麼問題〕
- 技術棧：〔技術棧，例如 Node.js + TypeScript〕
- 主要功能（只列我確定有做的）：〔功能1〕〔功能2〕〔功能3〕
- 安裝方式：〔實際安裝指令〕
- 最基本的使用範例：〔一段能跑的指令或程式碼〕
- 需要的環境變數或設定：〔有的話填，沒有寫「無」〕
- 授權：〔例如 MIT〕
- 專案性質：〔個人作品集 / 開源協作專案 / 內部工具〕

【要求】
1. 依這個順序產出區塊：標題與一句話定位、徽章（用 shields.io 語法，只放我事實裡有的：授權、技術棧版本，其餘留 TODO 註解）、功能特色、安裝步驟、使用範例、環境變數設定、貢獻指南、授權、致謝。
2. 若專案性質是「內部工具」，省略貢獻指南與致謝。
3. 截圖處放一個 Markdown 圖片語法佔位，並用註解標明「請替換成實際截圖」。
4. 絕對不要編造我沒提供的功能、參數或指令。任何你不確定的地方，用 <!-- TODO: 請補充 --> 註解標出，不要自己填。
5. 語氣像工程師寫給工程師，不要行銷口號、不要 emoji 開頭每一行。
6. 用繁體中文撰寫說明文字，程式碼與指令保持原樣。

請直接輸出 README.md 內容。

這段 Prompt 有幾個刻意的設計。第一，它明確要求 AI「不確定就標 TODO，不要自己填」——這一句話能擋掉大半的腦補。第二，它讓徽章只根據你給的事實產生，避免掛出假徽章。第三，它會依專案性質調整區塊，不會硬塞貢獻指南給你的個人小工具。

產完之後，真正的工作才開始

AI 給你的是草稿，不是成品。接下來這幾步，每一步都省不得。

逐行砍掉 AI 腦補的功能

這是最重要的一步。AI 會非常自信地寫出你根本沒實作的東西——因為它看不到你的程式碼，只能根據「這類專案通常有什麼」去補。它可能幫你的匯率工具加上「支援即時推播通知」，幫你的 CLI 加上一個 --verbose 參數，而這些你都沒做。打開程式碼，逐段對照，只要 README 寫的功能在程式裡找不到，就砍掉。README 承諾了、程式沒做到，比沒寫還糟，因為那是在騙使用者。

親手實測每一條安裝步驟

AI 寫的 npm install 加三行設定看起來很合理，但真的照著在一台乾淨的環境跑一次，你常會發現少了一個前置套件、環境變數名稱拼錯、或那個指令根本要 sudo。最可靠的做法是開一個全新的資料夾或容器，把自己當成第一次來的陌生人，照著 README 一字不漏地跑。跑不通的步驟，就是還沒寫完的步驟。

徽章只掛真的

徽章的價值在於「可信」。授權徽章、npm 版本徽章這種靜態的，填對就好；但 build passing、coverage 這種動態徽章，一定要真的接了 CI、真的有那個數字才掛。掛一個假的綠色 build passing，被同行點開一看是死連結或根本沒 CI，扣的分比不放還多。shields.io 上找得到各種徽章語法，但原則只有一條：沒有的資訊，就不要放那個徽章。

放一張讓人秒懂的截圖

文字說「它會輸出一張漂亮的比價表」，不如直接放那張表的截圖。CLI 工具就截終端機輸出，網頁就截畫面，有互動的就錄一段 GIF。這是整份 README 裡投報率最高的一塊——它讓路過的人在還沒讀任何文字前，就先看懂你做了什麼。

讓 README 幫你找到工作

如果這個專案是要放進履歷的作品集，README 的任務就不只是說明，而是「代替你在面試前先講一輪」。招募方點開你的 GitHub，平均只花幾十秒，他們要的不是欣賞你的程式碼，而是快速判斷：這個人能不能把一件事做完、交付得清不清楚、別人接不接得住他的東西。

所以開頭那一句話定位要對著「價值」寫，而不是對著「技術」寫。與其寫「使用 React 與 Node.js 開發的全端應用」，不如寫「幫接案設計師三秒算出報價的工具，省下每次翻 Excel 的時間」——前者只說了你用什麼，後者說了你解決了什麼，而後者才是招募方在意的。技術棧放進徽章跟後面的段落即可。

接著，讓整個專案透出「這個人很整齊」的訊號：README 有結構、commit 訊息乾淨、有基本的測試、授權清楚。這些細節單獨看都不起眼，加起來卻是很強的工程素養證明。一份用心的 README，傳達的潛台詞是「這個人交付的東西別人接得住」，而這正是任何團隊想要的人。

常見錯誤

• 讓 AI 寫出沒實作的功能：最常見也最傷的一種。README 承諾了程式做不到的事，使用者照做卻壞掉，信任一次就崩。產完一定逐項對照程式碼。
• 安裝步驟沒實測：直接把 AI 給的指令貼上去，自己從沒在乾淨環境跑過。別人照做第一步就卡住，直接關頁。
• 掛假徽章：沒接 CI 卻放 build passing、隨便填一個覆蓋率數字。被看穿就是減分。
• 一句話定位在講技術而不是講價值：開頭寫一堆用了什麼框架，卻沒說這東西解決誰的什麼問題，讀者沒有理由往下看。
• 整份都是 AI 腔：每一段都是「本專案旨在提供一個強大而優雅的解決方案」這種空話。刪掉形容詞，講具體的事。
• 忘了放授權：沒有 License，法律上別人不能安心使用或修改你的程式碼，等於把想幫你的人擋在門外。
• README 比專案還浮誇：一個一百行的小腳本配一份有行為準則、路線圖、贊助按鈕的 README，反差感讓人覺得虛。

AI 幫不上的界線

AI 能幫你把 README 的結構、排版、措辭處理得又快又好，但有幾件事它做不了，得靠你。

它不知道你的程式實際上做了什麼。它只能根據你的描述加上通用經驗去猜，所以每一項技術事實都要你查核。它也不知道你在設計上做過哪些取捨、為什麼選這個方案而不是那個——而這些「為什麼」往往是讓看的人覺得你有想法的關鍵，得你自己補進去。

更重要的是，它跑不了你的專案。安裝步驟通不通、範例輸出對不對，只有你在真實環境跑過才知道。AI 給你的是一份看起來很完整的草稿，但「看起來完整」和「真的能用」之間那道溝，只能由你這個唯一跑得動這個專案的人來填。

把分工想清楚就好：AI 負責把空白變成草稿、把亂的變整齊；你負責當事實查核員，確保每一個字都是真的。這樣產出的 README，才既有效率、又值得信任。

動手把你的下一個專案寫好

下次要把 side project 推上 GitHub，別再只留一行說明了。花十分鐘把專案事實列成清單，套上面那段 Prompt 生出骨架，再花二十分鐘逐項核對、實測、補截圖——這半小時，可能就是你那個專案被人看見、甚至被招募方記住的分水嶺。

想讓文件與程式的整套流程都更順，可以接著看 AgentAI 智庫的 用 AI 寫技術文件，把 API 說明也一起做好；或看 用 AI 寫 Git commit 訊息，讓你的提交歷史跟 README 一樣整齊。想從源頭把程式寫得更好，用 AI 寫程式的提示技巧 與 Cursor 怎麼用 也值得一讀。更多繁體中文的 AI 實戰教學，都在 AgentAI 智庫。

常見問題 FAQ

延伸閱讀

• 用 AI 寫技術文件
• 用 AI 寫 Git commit 訊息
• 用 AI 寫程式（提示技巧）
• Cursor 怎麼用？