create-rule
Use when found gap or repetative issue, that produced by you or implemenataion agent. Esentially use it each time when you say "You absolutly right, I should have done it differently." -> need create rule for this issue so it not appears again.
NeoLabHQ · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add NeoLabHQ/context-engineering-kit --skill create-rule技能说明
name: create-rule description: Use when found gap or repetative issue, that produced by you or implemenataion agent. Esentially use it each time when you say "You absolutly right, I should have done it differently." -> need create rule for this issue so it not appears again.
Create Rule
Guide for creating effective .claude/rules files with contrastive examples that improve agent accuracy.
Overview
Core principle: Effective rules use contrastive examples (Incorrect vs Correct) to eliminate ambiguity.
REQUIRED BACKGROUND: Rules are behavioral guardrails, that load into every session and shapes how agents behave across all tasks. Skills load on-demand. If guidance is task-specific, create a skill instead.
About Rules
Rules are modular, always-loaded instructions placed in .claude/rules/ that enforce consistent behavior. They act as "standing orders" — every agent session inherits them automatically.
What Rules Provide
- Behavioral constraints — What to do and what NOT to do
- Code standards — Formatting, patterns, architecture decisions
- Quality gates — Conditions that must be met before proceeding
- Domain conventions — Project-specific terminology and practices
Rules vs Skills vs CLAUDE.md
| Aspect | Rules (.claude/rules/) | Skills (skills/) | CLAUDE.md |
|---|---|---|---|
| Loading | Every session (or path-scoped) | On-demand when triggered | Every session |
| Purpose | Behavioral constraints | Procedural knowledge | Project overview |
| Scope | Narrow, focused topics | Complete workflows | Broad project context |
| Size | Small (50-200 words each) | Medium (200-2000 words) | Medium (project summary) |
| Format | Contrastive examples | Step-by-step guides | Key-value / bullet points |
When to Create a Rule
Create when:
- A behavior must apply to ALL agent sessions, not just specific tasks
- Agents repeatedly make the same mistake despite corrections
- A convention has clear right/wrong patterns (contrastive examples possible)
- Path-specific guidance is needed for certain file types
Do NOT create for:
- Task-specific workflows (use a skill instead)
- One-time instructions (put in the prompt)
- Broad project context (put in CLAUDE.md)
- Guidance that requires multi-step procedures (use a skill)
Rule Types
Global Rules (no paths frontmatter)
Load every session. Use for universal constraints.
# Error Handling
All error handlers must log the error before rethrowing.
Never silently swallow exceptions.
Path-Scoped Rules (paths frontmatter)
Load only when agent works with matching files. Use for file-type-specific guidance.
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
All API endpoints must include input validation.
Use the standard error response format.
Priority Rules (evaluator/judge guidance)
Explicit high-level rules that set evaluation priorities.
# Evaluation Priorities
Prioritize correctness over style.
Do not reward hallucinated detail.
Penalize confident wrong answers more than uncertain correct ones.
Rule Structure: The Contrastive Pattern
Every rule MUST follow the Description-Incorrect-Correct template. This structure eliminates ambiguity by showing both what NOT to do and what TO do.
Required Sections
---
title: Short Rule Name
paths: # Optional but preferable: when it is possible to define, use it!
- "src/**/*.ts"
---
# Rule Name
[1-2 sentence description of what the rule enforces and WHY it matters.]
## Incorrect
[Description of what is wrong with this pattern.]
\`\`\`language
// Anti-pattern code or behavior example
\`\`\`
## Correct
[Description of why this pattern is better.]
\`\`\`language
// Recommended code or behavior example
\`\`\`
## Reference
[Optional: links to documentation, papers, or related rules.]
Why Contrastive Examples Work
Researches shows that rules with both positive and negative examples are significantly more discriminative than rules with only positive guidance. The Incorrect/Correct pairing:
- Eliminates ambiguity — the agent sees the exact boundary between acceptable and unacceptable
- Prevents rationalization — harder to argue "this is close enough" when the wrong pattern is explicitly shown
- Enables self-correction — agents can compare their output against both patterns
Writing Effective Rules
Rule Description Principles
Explicit, high-level guidance:
| Principle | Example |
|---|---|
| Prioritize correctness over style | "A functionally correct but ugly solution is better than an elegant but broken one" |
| Do not reward hallucinated detail | "Extra information not grounded in the codebase should be penalized, not rewarded" |
| Penalize confident errors | "A confidently stated wrong answer is worse than an uncertain correct one" |
| Be specific, not vague | "Functions must not exceed 50 lines" not "Keep functions short" |
| State the WHY | "Use early returns to reduce nesting — deeply nested code increases cognitive load" |
Incorrect Examples: What to Show
The Incorrect section must show a pattern the agent would plausibly produce. Abstract or contrived bad examples provide no value.
Effective Incorrect examples:
- Show the most common mistake agents make for this scenario
- Include the rationalization an agent might use ("this is simpler")
- Mirror real code patterns found in the codebase
Ineffective Incorrect examples:
- Obviously broken code no agent would produce
- Syntax errors (agents already avoid these)
- Patterns unrelated to the rule's concern
Correct Examples: What to Show
The Correct section must show the minimal change needed to fix the Incorrect pattern. Large rewrites obscure the actual lesson.
**Effective Correct example
阅读完整来源 ↗