第三堂共學

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,理由有兩個:

  1. 這個資料夾以後想備份到 GitHub。放上去之後,首頁顯示的就是這一份。
  2. 希望每次創作有進展,這一份會跟著更新。打開就知道現在做到哪。

課堂上做出來的那一份

四塊內容

AI 寫了什麼

03它先讀過資料夾,才動筆

它沒有直接套範本。它先去讀專案裡現有的草稿,然後寫出這四塊:

這是什麼一句話:這是哪一類作品的創作資料庫,用什麼軟體管理。
基本資料類型、主題、寫作語言、一句話簡介。還沒定案的地方,它標了「待確認」「草稿」。
專案狀態一張小表:目前在哪個階段、大綱寫到哪、角色設定到哪、世界觀整理到哪、最後更新日期。
資料夾結構每個子資料夾放什麼。

「專案狀態」那張表是它讀完草稿後自己填的:哪幾幕已經有草稿、哪幾幕還沒寫、哪些設定出現過但還沒整理成檔案。

怎麼讓它跟著更新

04兩個動作

在檔案裡做記號

「專案狀態」那一段的前後,它各放了一行看不見的標記,標出「這一段由 AI 維護」。下次更新,它只改標記中間,不會動到你手寫的其他部分。

把規則寫進說明書

在專案的 CLAUDE.md 加一節「README 維護規則」:創作內容有更新時,README 也要跟著更新。

做記號的那兩行不要手動刪掉,刪了它就找不到該改哪裡。它在檔案最上面也留了一行說明提醒這件事。

兩份檔案的分工

05README 給人看,CLAUDE.md 給 AI 看

README.md

這個專案是什麼、現在做到哪。寫給任何一個走進來的人。

CLAUDE.md

在這個專案裡要怎麼工作。寫給 AI,是它的規矩。

兩份都是 Markdown,都放在專案最外層,但讀者不一樣,寫的東西就不一樣。

帶得走的東西

請 AI 先讀過資料夾,再寫一份「這裡是什麼、現在做到哪」。

然後請它把「跟著更新」寫進說明書。

下次打開資料夾,先讀這一份。

留言

CYC 看過才會公開。

還沒有公開的留言。

看其他教材

留言