README 怎麼寫？給 AI Vibe Coder 的技術文件課

三個月後你看自己寫的程式碼，會跟第一次看別人的程式碼一樣陌生。README 就是寫給那個未來的自己，也是寫給接手的人。這篇帶你用最小必要結構寫出一份真正有用的 README，並且學會怎麼請 AI 幫你生初稿、怎麼讓 FastAPI 自動幫你做 API 文件。

README 的最小必要結構

一份堪用的 README，至少要有這幾個區塊：

# 天氣小工具

一句話說明這個專案做什麼。

## 功能
- 查詢即時天氣（OpenWeatherMap API）
- 使用者帳號和查詢歷史
- RESTful API，支援 JSON

## 安裝
git clone https://github.com/your/weather-app
cd weather-app
pip install -r requirements.txt
cp .env.example .env  # 填入你的 API Key

## 環境變數
OPENWEATHER_API_KEY=  # OpenWeatherMap API Key
SUPABASE_URL=  # Supabase Project URL
SUPABASE_KEY=  # Supabase anon key

## 執行
uvicorn main:app --reload

用 AI 生成 README 的正確方式

把專案的技術棧和功能講清楚，讓 AI 一次生出結構完整的初稿。

請幫我為這個 Python FastAPI 專案寫 README.md：

專案：天氣查詢 App
技術棧：Python 3.11、FastAPI、Supabase、OpenWeatherMap API
功能：使用者登入、查詢天氣、查詢歷史記錄

包含以下區塊：
- 專案說明（一句話）
- 功能列表
- 技術棧
- 安裝步驟（git clone → pip install → .env 設定）
- 環境變數說明（每個變數的用途）
- 如何執行（開發環境）
- API 端點概覽（表格，端點、方法、說明）
- 部署說明（Railway）

語言：繁體中文，程式碼區塊用英文

FastAPI 自動 API 文件

加好 docstring，/docs 頁面就會自動顯示這些說明，不需要額外維護一份 API 文件。

@app.get("/weather/{city}",
    summary="查詢城市天氣",
    description="回傳指定城市的即時溫度和天氣描述")
async def get_weather(
    city: str = Path(..., description="城市名稱，英文"),
    current_user: User = Depends(get_current_user)
) -> WeatherResponse:
    # /docs 頁面會自動顯示這些說明
    ...

程式碼注解原則

注解應該解釋「為什麼」，而不是「做什麼」，程式碼本身應該能說明「做什麼」。

def get_weather(city: str, units: str = "metric") -> dict:
    """查詢指定城市的即時天氣資訊。

    Args:
        city: 城市名稱，英文，例如 "Taipei"
        units: 溫度單位，metric（攝氏）或 imperial（華氏）

    Returns:
        包含 temperature 和 description 的字典

    Raises:
        HTTPException: 城市不存在或 API 呼叫失敗時
    """

讓文件保持最新的四個方法

1. 改功能時同步更新 README：把「更新 README」加進你的完成定義，沒有更新文件就算沒完成。
2. API 文件靠程式碼驅動：FastAPI 的 /docs 從 decorator 和 docstring 自動生成，保持程式碼正確就等於保持文件正確。
3. 定期用新人視角閱讀 README：假裝自己是第一次看這個專案，按照步驟跑一遍，找出過時的地方。
4. 用 AI 幫你更新：把改動告訴 AI，例如「我改了 API 的回傳格式，請幫我更新 README 的 API 端點說明」，很快就能完成。