README.md 是什麼:一個資料夾的門面
「資料夾裡那個 README.md 是做什麼的?我不寫程式,也需要嗎?」夥伴的提問
README 是「先讀我」:這裡是什麼、現在做到哪。課堂上請 AI 先讀過資料夾再寫一份,並讓它跟著進度更新。順便分清楚 README 給人看、CLAUDE.md 給 AI 看。
資料夾裡常常有一個檔案叫 README.md。名字的意思就是「先讀我」。
它是什麼
01一個資料夾的門面
README 是 Read Me,.md 代表它是用 Markdown 寫的純文字。它通常放在專案最外層,回答一個第一次走進來的人會問的問題:這裡是在做什麼的?
放在哪
專案資料夾的最外層。一個專案一份。
誰會讀
第一次打開這個資料夾的人。可能是合作的人,可能是半年後的你,也可能是 AI。
在網路上
專案放上 GitHub 這類平台之後,平台會自動把它排版好,顯示在專案首頁。
Markdown 的符號怎麼讀,在這一篇:Markdown 是什麼:三個符號就夠用。
不只是寫程式的人在用
02寫作的資料夾,也可以有一份
課堂上夥伴的專案是一部長篇作品的資料庫,裡面是設定、大綱、角色,沒有一行程式。嚮導還是請 AI 幫它補一份 README.md,理由有兩個:
- 這個資料夾以後想備份到 GitHub。放上去之後,首頁顯示的就是這一份。
- 希望每次創作有進展,這一份會跟著更新。打開就知道現在做到哪。
課堂上做出來的那一份
四塊內容
AI 寫了什麼
03它先讀過資料夾,才動筆
它沒有直接套範本。它先去讀專案裡現有的草稿,然後寫出這四塊:
「專案狀態」那張表是它讀完草稿後自己填的:哪幾幕已經有草稿、哪幾幕還沒寫、哪些設定出現過但還沒整理成檔案。
怎麼讓它跟著更新
04兩個動作
在檔案裡做記號
「專案狀態」那一段的前後,它各放了一行看不見的標記,標出「這一段由 AI 維護」。下次更新,它只改標記中間,不會動到你手寫的其他部分。
把規則寫進說明書
在專案的 CLAUDE.md 加一節「README 維護規則」:創作內容有更新時,README 也要跟著更新。
做記號的那兩行不要手動刪掉,刪了它就找不到該改哪裡。它在檔案最上面也留了一行說明提醒這件事。
兩份檔案的分工
05README 給人看,CLAUDE.md 給 AI 看
README.md
這個專案是什麼、現在做到哪。寫給任何一個走進來的人。
CLAUDE.md
在這個專案裡要怎麼工作。寫給 AI,是它的規矩。
兩份都是 Markdown,都放在專案最外層,但讀者不一樣,寫的東西就不一樣。
帶得走的東西
請 AI 先讀過資料夾,再寫一份「這裡是什麼、現在做到哪」。
然後請它把「跟著更新」寫進說明書。
下次打開資料夾,先讀這一份。
留言
CYC 看過才會公開。
還沒有公開的留言。