工程文件 2026-05-29 · 10 分鐘讀

工程師 README 寫法
12 個 Senior 習慣

README 不是「給陌生人看的客套文件」、是「你工程紀律的明信片」。HR 點進你 GitHub、看的第一個東西就是 README ─ 不用 30 秒就能判斷你是 Junior 還是 Senior。這篇拆給你看 ─ Senior 怎麼寫 README、加完整可 copy 模板。

為什麼README 比你想的重要

想像一個情境：

你投履歷給一家公司、HR 把你 GitHub 連結點開、隨機點進一個你最近的 repo。

沒 README ─ HR 滑 3 秒、關掉
只有 1 句 README ─ HR 看不出你做了什麼、關掉
README 寫得像樣 ─ HR 看 30 秒、知道你在解什麼問題、用什麼技術、決定花更多時間看你 code

差距不是「code 強弱」 ─ 是「你有沒有把工作整理成別人看得懂的東西」。

技術好的人很多。
技術好 + 能讓別人看懂自己做了什麼的人、少。
這就是 Senior 跟 Junior 的差別。

12 個 Senior 寫 README 的習慣

01 第一行：1 句話講清楚這是什麼

不要寫「This is a project I made for fun」。

要寫「用一句話講清楚 problem + solution + audience」：

# Mentry CLI
A command-line tool that audits your Next.js project for production-readiness ─
designed for solo developers shipping their first SaaS.

這一句要回答 3 個問題：

解決什麼問題？
用什麼方式？
給誰用？

02 放一張截圖或 demo gif

人類看圖比看文字快 60 倍（一般認知科學共識）。

每個 README 第一個區塊、放一張：

UI project → 截圖（最好是 light + dark mode）
CLI project → terminal recording (使用 asciinema、agg)
API project → curl 範例的截圖 / 流程圖
Library → code 使用範例的螢幕截圖

沒圖的 README = 沒封面的書。多數人不會翻開。

03 Badge 行 ─ 但不要塞滿

很多人 Badge 塞 15 個 ─ build / test / coverage / dependency / license / npm / downloads / discord / twitter ⋯⋯

Senior 通常只放 3-5 個關鍵的：

![Build](https://img.shields.io/github/actions/workflow/status/user/repo/test.yml)
![Version](https://img.shields.io/npm/v/your-package)
![License](https://img.shields.io/github/license/user/repo)

原則 ─ Badge 要傳達訊號、不是裝飾。

04 5 分鐘快速啟動區塊

這是檢查「軟體 vs code」最重要的一塊。

## Quick Start

```bash
git clone https://github.com/user/repo.git
cd repo
cp .env.example .env
npm install
npm run dev
```

Open http://localhost:3000 ─ should see the welcome page.

重點：

命令是「可以直接 copy-paste」的、不要寫成 prose
有 .env.example 的提示、不要假設讀者知道
最後一行寫「應該看到什麼」、讓人知道有沒有跑成功

05 把 prerequisites 寫清楚

不要假設讀者跟你一樣的環境。

## Prerequisites

- Node.js 20+
- pnpm 9+ (or npm 10+)
- PostgreSQL 15+ (or use the Docker setup below)
- OpenAI API key (free tier works for testing)

Senior 會列「最低版本」+ 「有沒有 fallback」。

06 用表格講設定

環境變數、config option、CLI flag ─ 全部用表格。

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | ✅ | - | PostgreSQL connection string |
| `OPENAI_API_KEY` | ✅ | - | Your OpenAI API key |
| `PORT` | ❌ | `3000` | Server port |
| `LOG_LEVEL` | ❌ | `info` | One of: debug, info, warn, error |

表格比 bullet list 好讀 5 倍。

07 用code block、不要寫散文

錯誤示範：

「To install, run npm install in the root directory, then create a .env file with your API key, and finally run npm start to launch the server on port 3000.」

Senior 寫法：

```bash
npm install
cp .env.example .env  # add your API key
npm start             # server runs on :3000
```

視覺資訊密度差 5 倍。

08 用「Why X over Y」交代技術選擇

這是 Junior 跟 Senior README 最大的差別。

Junior README：列技術棧。
Senior README：列技術棧 + 為什麼。

## Tech Stack

- **Next.js 15** ─ App Router + Server Actions, optimized for low-traffic SaaS
- **Drizzle ORM** ─ chosen over Prisma for better edge runtime compatibility
- **Cloudflare Pages** ─ free tier handles up to 100K req/day, no cold start
- **Stripe** ─ for subscription billing (was Lemon Squeezy, switched for tax handling)

這些「為什麼」傳達一件事 ─ 你不是隨便選工具、是想過 trade-off 的。HR / 面試官會把你升一級。

09 加一個「Project Structure」區塊

一個簡單的目錄結構、用 ASCII tree：

## Project Structure

```
src/
├── app/              # Next.js App Router pages
├── components/       # Shared React components
├── lib/
│   ├── db/           # Drizzle schema & queries
│   ├── auth/         # NextAuth config
│   └── ai/           # OpenAI wrappers
├── tests/            # Vitest unit tests
└── e2e/              # Playwright E2E tests
```

這個區塊讓新人 30 秒看完、知道「我要改 X、該去哪找」。

10 寫「How to Contribute」、即使是個人 project

這是讓 HR 印象深刻的小細節。

## Contributing

PRs welcome. Before submitting:

1. Run `npm test` ─ all tests should pass
2. Run `npm run lint` ─ no errors
3. Update relevant docs if you changed behavior
4. Write a clear PR description (the "why", not just "what")

有這個區塊 ─ 表示你想過「別人怎麼跟我合作」、不只是想過「我自己怎麼寫」。

11 用「Roadmap」展示思考

列出 3-5 個你已知但還沒做的事：

## Roadmap

- [x] CSV export
- [x] User authentication
- [ ] Multi-tenancy (planned Q3)
- [ ] Webhook support (depends on user demand)
- [ ] OAuth login (Google, GitHub)

See [Issues](https://github.com/user/repo/issues) for detailed planning.

Roadmap 顯示你知道現在缺什麼、想做什麼 ─ 這是 Senior 的特徵。

12 結尾放License + 致謝

## License

MIT ─ see [LICENSE](./LICENSE)

## Acknowledgements

- Inspired by [neetcode.io](https://neetcode.io) for the topic structure
- Logo by [@designer-handle](https://twitter.com/designer-handle)
- Built during the 100-day [Mentry Build in Public](https://mentry.dev) journey

致謝看似小事、實際上傳達 2 個訊號：

你不是孤狼、你會引用前人
你尊重智慧財產

HR / 開源 maintainer 看到致謝、會直接把你印象拉到「professional」。

完整README 模板（可直接 copy）

下面是把上面 12 條整合起來的完整模板、你可以複製到新 project 的 README.md 起始：

# Project Name

> One-sentence pitch ─ what it does, for whom, and the unique angle.

![Demo](./docs/demo.gif)

![Build](https://img.shields.io/github/actions/workflow/status/user/repo/test.yml)
![Version](https://img.shields.io/npm/v/your-package)
![License](https://img.shields.io/github/license/user/repo)

## ✨ Why This Exists

Briefly: what problem you saw, why existing solutions didn't fit,
what your approach is.

## 🚀 Quick Start

```bash
git clone https://github.com/user/repo.git
cd repo
cp .env.example .env  # fill in API keys
npm install
npm run dev
```

Open http://localhost:3000 ─ should see the welcome page.

## 📦 Prerequisites

- Node.js 20+
- pnpm 9+ (or npm 10+)
- PostgreSQL 15+ (or use included Docker setup)

## ⚙️ Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | ✅ | - | PostgreSQL connection string |
| `API_KEY` | ✅ | - | Your service API key |
| `PORT` | ❌ | `3000` | Server port |

## 🏗️ Tech Stack

- **Next.js 15** ─ App Router for incremental adoption
- **Drizzle ORM** ─ chosen for edge runtime compatibility
- **Tailwind CSS** ─ utility-first, easy to customize
- **Vitest** ─ faster than Jest for our use case

## 📁 Project Structure

```
src/
├── app/              # Next.js routes
├── components/       # Shared UI
├── lib/              # Business logic
├── tests/            # Unit tests
└── e2e/              # E2E tests
```

## 🧪 Testing

```bash
npm test              # unit tests
npm run test:e2e      # end-to-end
npm run test:watch    # watch mode
```

## 🤝 Contributing

PRs welcome! Before submitting:

1. Run `npm test` ─ all tests pass
2. Run `npm run lint` ─ no errors
3. Update relevant docs
4. Write a clear PR description (why, not just what)

## 🗺️ Roadmap

- [x] Core feature A
- [x] Core feature B
- [ ] Multi-tenancy (planned next quarter)
- [ ] Webhook support

## 📜 License

MIT ─ see [LICENSE](./LICENSE)

## 🙏 Acknowledgements

- Inspired by [project-name](https://example.com)
- Built during [Project Name](https://example.com) journey

最後一個提醒

一個寫得好的 README、可能比 100 行 commit 影響你下次面試多 10 倍。
因為它是面試官、HR、未來同事、跟未來的你會看的第一個檔案。

這個禮拜花 30 分鐘、回頭把你 GitHub 上 1 個最有代表性的 repo README 重寫。下次有人點進去、他看到的會是不一樣的你。

想要有人 review 你的 GitHub 整個門面？

30 分鐘 1-on-1 諮詢 NT$1,500 ─ 我幫你看 README、project structure、commit history、整體呈現、給你具體要改什麼的清單。

LINE 預約諮詢先訂閱 Newsletter

工程師 README 寫法12 個 Senior 習慣