agent-rules-books: Classic Software Books Distilled into AGENTS.md Rules

## What it is / what pain point it solves agent-rules-books 'distills' multiple software engineering classics into rule sets for AI coding agents. The pain point: writing a single line in AGENTS.md / CLAUDE.md like 'please follow Clean Code' barely changes AI behavior — just naming a book is far less effective than giving concrete, actionable instructions. This project extracts the principles from these books into imperative rules (e.g., 'if a function both changes state and returns an answer, split it,' 'comments should explain why, not narrate bad code'), giving the agent clear guidance when generating, reviewing, or refactoring code. ## Why this source is worth using MIT licensed, free to use and modify; broad coverage — currently distilling 14 heavyweight classics, including: A Philosophy of Software Design, Clean Architecture, Clean Code, Code Complete, Designing Data-Intensive Applications, Domain-Driven Design (both the Distilled and Implementing editions), Patterns of Enterprise Application Architecture, Refactoring, Release It!, The Pragmatic Programmer, Working Effectively with Legacy Code, and Refactoring.Guru. The author also notes that in testing, 'rule-based guidance' clearly outperforms just dropping the book title. ## Full / mini / nano: what's different Each book comes in three sizes for different context budgets: - full: the complete version (roughly 300+ lines, 150+ rules) — use when you need full coverage. - mini: the recommended everyday-production version (roughly 45–65 lines, 28–47 rules), the sweet spot between completeness and brevity — the maintainers recommend this version for most situations. - nano: a heavily compressed fallback (roughly 32–44 lines, 14–26 rules) — use when context is very tight. All three versions share the same core principles; they're just compressed to different degrees. ## How to use it (steps) 1. Go to the repo and pick the directory for the book you want (e.g. clean-code, refactoring, domain-driven-design). 2. Each directory contains three files: BookName.md (full), BookName.mini.md, and BookName.nano.md. 3. Pick a version based on your context budget and manually copy the content into your project's AGENTS.md, CLAUDE.md, Cursor rules, or Copilot instructions (there's no install script). 4. You can mix multiple books (e.g. Clean Code mini plus Refactoring nano at the same time). ## When to use it When you want AI to maintain a consistent design taste in this repo over the long term (clean naming, sensible refactoring timing, DDD boundaries), pin the corresponding rules into your agent config file and you're set going forward; the full_prompt above uses the Clean Code mini edition as an example, rewritten into a directly pastable rule block. Source: ciembor/agent-rules-books (MIT License) — this entry is a rewritten/reorganized summary with rule wording rephrased; see the source link for the original.

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

# 程式碼品質規則集（mini 版・改寫自 agent-rules-books / Clean Code 為例）

你在本專案產生、審查或重構程式碼時，請遵守下列規則。將本段貼入 {{AGENT_FILE}}（如 AGENTS.md / CLAUDE.md / .cursorrules）。

## 何時套用
撰寫新程式、審查 PR、或重構既有程式碼時皆適用。

## 首要修正的偏誤
優先消除：含糊命名、過長且混雜多層抽象的函式、隱藏的副作用、用註解去解釋本該寫清楚的爛 code。

## 決策規則
- 保留既有行為，為「下一個讀者」而寫，在你動到的範圍內讓程式更乾淨（童子軍規則）。
- 用精準命名、一個概念只用一個詞；讓程式能被局部推理（不必跳全檔才看懂）。
- 把布林旗標、混雜的抽象層級、隱藏副作用從函式裡拆出去。
- 命令（會改狀態）與查詢（只回傳值）分離；參數量保持精簡且有意義。
- 讓 happy path 清楚可讀；把無效狀態、錯誤與清理顯式化，而非藏在隱性流程裡。
- 註解只用來說明「為什麼／合約」，不要用來解釋讓人看不懂的程式。

## 觸發規則
- 當一個函式既改狀態又回傳答案 → 拆成兩個。
- 當你需要寫註解解釋流程 → 先把程式簡化到不需要那條註解。

## 最終檢查清單
- [ ] 命名是否精準、單一概念單一詞？
- [ ] 函式是否只做一件事、抽象層級一致？
- [ ] 有無隱藏副作用或命令／查詢混用？
- [ ] 錯誤與邊界是否顯式處理？

（依需求可換成其他書：refactoring、domain-driven-design、the-pragmatic-programmer、working-effectively-with-legacy-code 等；每本都有 full／mini／nano 三尺寸。）

---
📎 來源：ciembor/agent-rules-books（MIT 授權）— 本篇為繁中改寫整理，規則措辭已重寫、非逐字照搬，原始 14 本書的完整規則集與三種尺寸見上方連結。