黑客松 README 建構器
黑客松 README 有一項普通專案 README 沒有的任務：它必須贏得比賽。 評審在幾分鐘內瀏覽數十個儲存庫，通常是在手機上，決定哪些值得 打開。README 是專案的第一印象，而且常常是評審在評分前唯一閱讀的 文件。所以目標不是「記錄程式碼」——而是讓一位忙碌、持懷疑態度的 評審快速理解並相信這個專案，並且讓每一個主張都能輕易被驗證。
這個技能會產出一個豐富的提交風格的 README，而不是一個簡陋的。
參考的外觀與風格存放在 references/readme-template.md 中——在開始
撰寫前請先閱讀它，因為它編碼了風格指南（置中徽章行、示範
徽章按鈕、表格、基於事實的步驟、專案樹、明確的「評審亮點」區塊）。
references/badges.md 中有可直接複製貼上的 shields.io 片段。
請按順序執行以下步驟，但保持對話感——你正在幫助一位疲憊的參賽者 衝過終點線，而不是填寫一份表單。
步驟 1 — 錨定評審標準（先做這個）
這是你能做的最有影響力的事情，也是這個技能存在的原因。 大多數 README 是根據通用模板撰寫的；而獲勝的 README 是根據評分標準 撰寫的。在開始其他事情之前，先問：
「你有活動的評審標準或評分表嗎？（例如，'創新性、技術難度、影響力、完整性'，或是一份評分表/提交頁面的提示。）如果有的話請貼給我——我會確保每一項都清楚地被涵蓋。如果沒有的話，我會使用一個可靠的預設值。」
為什麼要先問：如果評分標準重視「現實世界的影響力」，就用一個生動的 問題和受眾來開頭；如果它重視「技術難度」，就把架構和困難的部分放在 前面。你稍後會在 README 結尾附近添加一個評審亮點區塊，列出每個 標準並指向專案如何滿足該標準——這是讓錨定評分標準變得可見的方式， 評審喜歡這個，因為它幫他們做了工作。保持一個核對清單：每個標準 都需要在 README 中有一個歸屬。
如果他們沒有評分標準，預設使用幾乎每個活動都會使用的某個版本的四個 標準：創新性/原創性、技術執行、影響力/實用性、以及完善度/完整性。
同時評估一下活動的風格，因為它會影響哪些可選區塊應該被包含 （見步驟 4）：
- 學術/研究/技術衝刺（例如 ACM 活動）：通常會獎勵 AI 使用揭露、 倫理/資料保護說明、參考文獻/引用，有時還有聯合國永續發展目標 對齊。包含這些。
- 產品/新創/一般週末黑客松：保持精簡——除非專案真的涉及資料收集或 需要證據的主張，否則跳過永續發展目標、倫理和引用。
如果不確定，就詢問，或者包含較輕量的選項並提及其他的可以索取。
步驟 2 — 掃描儲存庫以基於事實
當 README 描述的專案與程式碼不符，或設定步驟無法執行時，評審會 立刻失去信任。所以在開始撰寫前，先看看實際有什麼。風格指南會引用 真實的檔案路徑並顯示真實的命令與預期輸出——你只有閱讀儲存庫才能 做到這一點。
- 技術棧與語言：從清單中推斷——
package.json、requirements.txt、pyproject.toml、go.mod、Cargo.toml、pom.xml、Gemfile。記下框架（React、Next、Vite、FastAPI、Flask、Three.js…）。 這些直接對應到徽章行和技術棧表格。 - 如何執行：閱讀
package.json中的scripts、Makefile、docker-compose.yml、Procfile、.env.example。執行區塊必須與專案 實際啟動方式相符，包括環境變數和真實的開發埠。如果可以推斷出 預期輸出，就顯示它——這表示專案是可運作的。 - 結構與進入點：瀏覽頂層目錄和主要的進入點檔案，以便專案樹和
「如何運作」步驟引用真實的檔案（
src/lib/check.js、app/main.py）， 就像範例那樣。 - 已有內容：部分的 README、LICENSE、
assets//docs//public/中的螢幕截圖、設定檔中的已部署網址、CI 工作流程。重複使用它們。
如果你沒有儲存庫存取權（使用者只描述專案），跳過掃描，依賴訪談， 並說明情況——標記設定指令和檔案路徑是佔位符，需要驗證，而不是 憑空創造精確的路徑。
步驟 3 — 訪談，獲取程式碼無法提供的資訊
儲存庫提供事實；參賽者提供故事和證據。用一個友善的批次詢問這些， 並清楚說明他們可以跳過任何項目：
- 一句話宣傳語 → 變成標語塊引用。
- 問題/靈感 → 具體、人性化，最好是一個特定的時刻。
- 線上展示 + 影片 → 被點擊最多的資產。將它們靠近頂部作為 徽章按鈕呈現。如果沒有影片，溫和地指出一個 2 分鐘的影片會非常有幫助。
- 螢幕截圖/GIF/吉祥物或標誌 → 即使一張圖片也能提升觀感上的 完善度；範例會將吉祥物/預覽圖片置頂居中。
- 困難的部分 → 技術上棘手或他們引以為傲的部分；對於技術執行 評分和「如何運作」部分來說是黃金材料。
- 主要成果/指標 → 如果專案測量了任何東西，一個小成果表格會 非常有說服力。
- 團隊 → 團隊表格的姓名 + 角色（以及連結）。
- 下一步 → 路線圖/擴展願景。
- 活動補充（僅在步驟 1 中判斷相關時）→ 使用的 AI 工具、資料/同意 細節、引用。
不要因為沒有答案就卡住。如果他們沒時間了，就用清楚標記的佔位符
（例如 <!-- TODO: 加入展示連結 -->）來起草，這樣重要的事情就不會
被默默捨棄——絕對不要偽造展示網址、指標或團隊成員。
步驟 4 — 撰寫 README
在專案根目錄（或使用者指定的位置）產生一個 README.md 檔案，
遵循 references/readme-template.md。完整的排序骨架在那個檔案裡；
這裡是形狀以及哪些部分是核心 vs 可選。
核心（幾乎總是包含）：
- 標題 + 可選的置中標誌/吉祥物圖片
- 置中的技術徽章行（來自
references/badges.md） - 活動/提交行 + 標語塊引用
- 展示 + 影片作為徽章按鈕（以及資料集/Colab 連結，如果有的話）
- 團隊表格
- 問題（或「為什麼這很重要」）
- 解決方案 / 它做什麼
- 如何運作 — 引用真實檔案的編號步驟
- 技術棧表格
- 本地執行 — 經過驗證的命令，如果可能的話包含預期輸出
- 專案結構樹
- 路線圖 / 下一步
- 評審亮點 — 每個標準一個要點，將專案與其對應
- 授權條款
可選（根據活動風格和實際情況包含）：
- 英雄區下方的錨點連結導航列（3–6 個主要區塊）——將長卷軸變為 評審在手機上瀏覽時的一次點擊。
- 主要成果/指標表格 + 錯誤/分析表格（資料專案）；連結原始資料或 可重現的命令，以便數字是可重複執行的。
- 當專案改進了現狀（更快、更便宜、步驟更少）時，一個前後對比 的 50/50 表格——它讓優勢視覺化，而不是宣稱。
- 對於只有一個殺手級數字的專案，在英雄區下方放一個 ASCII 統計框。
> [!IMPORTANT]/> [!NOTE]GitHub 警示提醒，用來突出顯示一個 瀏覽中的評審絕不能錯過的關鍵事實或注意事項（謹慎使用）。- Mermaid 流程圖（多階段系統）
- 示範流程 / 「哪些部分可以離線使用」風格的逐步解說
- AI 使用揭露（學術活動）
- 資料保護/隱私/倫理（涉及人員或資料的專案）
- 聯合國永續發展目標對齊（注重影響力的學術活動）
- 參考文獻與引用、致謝
- 當前狀態核對清單 + 評審前完善待辦事項
根據步驟 1 的評分標準調整重點和順序：最重要的標準應該出現在最前面。 不要填充——每個區塊都應該值得它的位置。一個精簡的產品黑客松可能 只使用核心組；一個研究型技術衝刺可能使用大部分可選組。符合專案， 而不是核對清單。
對評審重要的風格注意事項：
- 以最強的重點開頭——創新性、工程實力或影響力，哪個是鉤子就用哪個。
- 展示，不要只是告訴——一個展示徽章按鈕、一個 GIF、一個一鍵設定、 一個預期輸出區塊勝過形容詞。每一個令人印象深刻的宣稱都應該是 可驗證的。前後對比表格、統計框或可重現的基準測試能將宣稱轉化為 評審可以看見或重新執行的證據。
- 讓英雄區發揮作用——置中標題、可選標誌/吉祥物、徽章行和一個 精準的標語應該能讓評審在滾動之前就明白這是什麼以及為什麼它很好。 將展示/影片按鈕放在這裡，也就是第一個點擊的落點。
- 一切基於儲存庫——真實的檔案路徑、真實的命令、真實的開發埠。 這就是讓 README 值得信賴的原因，也是範例風格的連貫主線。
- 誠實——不要宣稱不存在的功能；評審會測試東西，一個破滅的宣稱 比缺少功能更糟糕。將未完成的工作標記在「下一步」或狀態核對清單中， 而不是當作已完成的。
- 保持易於瀏覽——短段落、有意義的標題、表格勝過文字牆、 在手機上兩分鐘內可從上到下閱讀。
步驟 5 — 根據評分標準閉環
在交付之前，逐一檢查步驟 1 中的每個標準，確認「評審亮點」區塊 （以及內文）有回應它；如果任何標準沒有歸屬，就添加它。然後告訴 使用者你做了什麼——例如「你的評分標準重視影響力和技術難度；我以 問題開頭來強調影響力，並在「如何運作」下添加了「為什麼這很難」的 說明，而「評審亮點」區塊列出了全部四個。」最後，列出任何剩餘的 佔位符（展示連結、螢幕截圖、指標），以便他們確切知道在提交前需要 填寫什麼。