mod

Author: yunbow

03_guidelines/common/ai-coding.md

@@ -164,7 +164,38 @@ If AI consistently fails to follow a specific guideline:
 3. Add the rule to the project's checklist template
 4. If still failing, consider adding a pre-commit hook or linter rule for automated enforcement
 
-## 5.4 Rule Suppression (Escape Hatch)
+## 5.4 How to Write Effective Guidelines (Benchmark-Validated)
+
+[Benchmark data](https://github.com/yunbow/ai-dev-os-benchmark) shows that guideline **specificity** — not quantity — determines AI compliance. Vague rules are ignored; specific rules achieve 100% compliance.
+
+### Rules for writing rules:
+
+| Principle | Bad (0% compliance) | Good (100% compliance) |
+|-----------|---------------------|------------------------|
+| **Name the exact method** | "Validate date ranges" | "MUST use `.refine()` to check `dueDate > new Date()`" |
+| **Name the exact pattern** | "Use exhaustive checks" | "MUST use `default: { const _exhaustive: never = status; }`" |
+| **Provide decision criteria** | "Use dynamic imports" | "SHOULD use `next/dynamic` for components with dependencies > 50KB: charts, editors, modals" |
+| **Show the anti-pattern** | "Use proper naming" | "❌ `handleDelete` ✅ `handleTaskDelete` (MUST include noun)" |
+| **Use MUST/SHOULD keywords** | "Consider using..." | "MUST validate on BOTH client and server using `zodResolver`" |
+
+### What NOT to include in guidelines:
+
+* General best practices the AI already knows (basic error handling, standard naming, RESTful API design)
+* Large Before/After code sections (benchmark shows no improvement, +55% tokens wasted)
+* YAML frontmatter or structured metadata (benchmark shows no improvement, +33% tokens wasted)
+* Abstract principles without concrete implementation guidance
+
+### The "generate → check → fix" workflow:
+
+Guidelines alone produce near-zero improvement in total code quality scores. The primary quality mechanism is **post-generation verification** via `/ai-dev-os-check`:
+
+1. Load 3-5 project-specific guideline files in CLAUDE.md (~8K tokens)
+2. AI generates code
+3. Run `/ai-dev-os-check` with a specific checklist
+4. AI reviews its own code and fixes violations
+5. This workflow scores 96.9/100 in benchmarks
+
+## 5.5 Rule Suppression (Escape Hatch)
 When a specific guideline rule is not applicable to a particular module or file, suppress it explicitly rather than ignoring it silently:
 
 * **Project-level suppression**: Add a `project-specific/` guideline that overrides the rule for specific directories or modules. The Specificity Cascade ensures project-specific rules take precedence over common rules.

README.md

@@ -188,6 +188,7 @@ git commit -m "chore: pin ai-dev-os to v1.2.0"
 | [plugin-kiro](https://github.com/yunbow/ai-dev-os-plugin-kiro) | Steering Rules and Hooks for Kiro |
 | [plugin-cursor](https://github.com/yunbow/ai-dev-os-plugin-cursor) | Cursor Rules (.mdc) for guideline-driven development |
 | [cli](https://github.com/yunbow/ai-dev-os-cli) | Setup automation — `npx ai-dev-os init` |
+| [benchmark](https://github.com/yunbow/ai-dev-os-benchmark) | Quantitative benchmark — guideline impact on AI code quality |
 
 ## License
 

docs/i18n/es/README.md

@@ -188,6 +188,7 @@ git commit -m "chore: pin ai-dev-os to v1.2.0"
 | [plugin-kiro](https://github.com/yunbow/ai-dev-os-plugin-kiro) | Steering Rules y Hooks para Kiro |
 | [plugin-cursor](https://github.com/yunbow/ai-dev-os-plugin-cursor) | Cursor Rules (.mdc) para desarrollo guiado por directrices |
 | [cli](https://github.com/yunbow/ai-dev-os-cli) | Automatización de configuración — `npx ai-dev-os init` |
+| [benchmark](https://github.com/yunbow/ai-dev-os-benchmark) | Benchmark cuantitativo — impacto de directrices en calidad |
 
 ## Licencia
 

docs/i18n/ja/README.md

@@ -188,6 +188,7 @@ git commit -m "chore: pin ai-dev-os to v1.2.0"
 | [plugin-kiro](https://github.com/yunbow/ai-dev-os-plugin-kiro) | Kiro 向けの Steering Rules と Hooks |
 | [plugin-cursor](https://github.com/yunbow/ai-dev-os-plugin-cursor) | ガイドライン駆動開発のための Cursor Rules (.mdc) |
 | [cli](https://github.com/yunbow/ai-dev-os-cli) | セットアップ自動化 — `npx ai-dev-os init` |
+| [benchmark](https://github.com/yunbow/ai-dev-os-benchmark) | 定量ベンチマーク — ガイドラインの品質影響データ |
 
 ## ライセンス
 

docs/i18n/ko/README.md

@@ -188,6 +188,7 @@ git commit -m "chore: pin ai-dev-os to v1.2.0"
 | [plugin-kiro](https://github.com/yunbow/ai-dev-os-plugin-kiro) | Kiro용 Steering Rules와 Hooks |
 | [plugin-cursor](https://github.com/yunbow/ai-dev-os-plugin-cursor) | 가이드라인 기반 개발을 위한 Cursor Rules (.mdc) |
 | [cli](https://github.com/yunbow/ai-dev-os-cli) | 설정 자동화 — `npx ai-dev-os init` |
+| [benchmark](https://github.com/yunbow/ai-dev-os-benchmark) | 정량적 벤치마크 — 가이드라인 품질 영향 데이터 |
 
 ## 라이선스
 

docs/i18n/zh-CN/README.md

@@ -188,6 +188,7 @@ git commit -m "chore: pin ai-dev-os to v1.2.0"
 | [plugin-kiro](https://github.com/yunbow/ai-dev-os-plugin-kiro) | Kiro 的 Steering Rules 与 Hooks |
 | [plugin-cursor](https://github.com/yunbow/ai-dev-os-plugin-cursor) | 指南驱动开发的 Cursor Rules (.mdc) |
 | [cli](https://github.com/yunbow/ai-dev-os-cli) | 设置自动化 — `npx ai-dev-os init` |
+| [benchmark](https://github.com/yunbow/ai-dev-os-benchmark) | 定量基准测试 — 指南对代码质量的影响 |
 
 ## 许可证