Skip to content

docs: Improve rule documentation placement guidelines #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 10, 2025
Merged

docs: Improve rule documentation placement guidelines #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/guides/en/rule-editing-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,27 @@ Conversely, LLM execution accuracy can easily degrade depending on rule file con
With the premise that complete control is impossible, executing tasks, reflecting on issues that arise, and feeding back into the system enables maintaining and improving execution accuracy.
When using this in actual projects and results don't match expectations, consider improving rule files.

## Determining Where to Document Rules

### File Roles and Scope

| File | Scope | When Applied | Example Content |
|------|-------|--------------|-----------------|
| **CLAUDE.md** | All tasks | Always | Approval required before Edit/Write, stop at 5+ file changes |
| **Rule files** | Specific technical domains | When using that technology | Use specific types, error handling required, functions under 30 lines |
| **Guidelines** | Specific workflows | When performing that workflow | Sub-agent selection strategies |
| **Design Docs** | Specific features | When developing that feature | Feature requirements, API specifications, security constraints |

### Decision Flow

```
When is this rule needed?
├─ Always → CLAUDE.md
├─ Only for specific feature development → Design Doc
├─ When using specific technology → Rule files
└─ When performing specific workflow → Guidelines
```

## 9 Rule Principles for Maximizing LLM Execution Accuracy

Here are 9 rule creation principles based on LLM characteristics and this boilerplate's design philosophy.
Expand Down
21 changes: 21 additions & 0 deletions docs/guides/ja/rule-editing-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,27 @@ LLMの出力を完全に制御することは不可能ですが、仕組みを
完全に制御することはできないという前提を持った上でタスクを実行させ、生じた課題を振り返り、仕組みにフィードバックをしていくことで、実行精度の維持向上が実現します。
実際のプロジェクトで活用し、思ったような結果にならなかった時は、ルールファイルの改善を検討してみてください。

## どのファイルに記載するべきかの判断基準

### ファイルごとの役割と適用範囲

| ファイル | 適用範囲 | 適用タイミング | 記載する内容の例 |
|---------|----------|--------------|--------------|
| **CLAUDE.md** | 全タスク | 常時適用 | Edit/Write前の承認必須、5ファイル以上変更で停止 |
| **ルールファイル** | 特定技術領域 | その技術使用時 | 具体的な型を使用、エラーハンドリング必須、関数30行以内 |
| **ガイドライン** | 特定作業 | その作業実施時 | サブエージェントの使い分け方 |
| **Design Doc** | 特定機能 | その機能開発時 | その機能の必須要件、APIの仕様、セキュリティ制約 |

### 判断フローチャート

```
いつこのルールが必要か？
├─ 常に必要 → CLAUDE.md
├─ 特定機能の開発時のみ → Design Doc
├─ 特定技術を使用する時 → ルールファイル
└─ 特定の作業を行う時 → ガイドライン
```

## LLMの実行精度を最大化する9つのルール原則

LLMの特性と本ボイラープレートの設計思想を踏まえた、ルール作成の原則を9つ紹介します。
Expand Down