["Rules are concise guidelines (not detailed workflows)","Use markdown formatting for clarity","Group related rules into sections","Keep rules under 50 lines unless detailed guidance needed"]
error_handling
graceful
streaming
supported
output_location
.claude/rules/
verified
true
lastVerifiedAt
2026-02-28
dependencies
["research-synthesis"]
source
builtin
trust_score
100
provenance_sha
541cc04a82aab316
Rule Creator
Create rule files in .claude/rules/. Rules are auto-discovered by Claude Code and loaded into agent context.
Step 0: Check for Existing Rule
Before creating, check if rule already exists:
test -f .claude/rules/<rule-name>.md && echo"EXISTS" || echo"NEW"
If EXISTS → use Read to inspect the current rule file, then Edit to apply changes directly. Run the post-creation integration steps (Step 4) after updating.
If NEW → continue with Step 0.5.
Step 0.5: Companion Check
Before proceeding with creation, run the ecosystem companion check:
Use companion-check.cjs from .claude/lib/creators/companion-check.cjs
Call checkCompanions("rule", "{rule-name}") to identify companion artifacts
Review the companion checklist — note which required/recommended companions are missing
Plan to create or verify missing companions after this artifact is complete
Include companion findings in post-creation integration notes
This step is informational (does not block creation) but ensures the full artifact ecosystem is considered.
# Testing## Test-Driven Development- Use TDD for new features and bug fixes (Red-Green-Refactor cycle)
- Write failing test first, then minimal code to pass, then refactor
Never write production code without a failing test first
Add unit tests for utilities and business logic
Add integration tests for API boundaries
Keep tests deterministic and isolated (no shared state)
Place test files in directory mirroring source structure
-
## Test Organization
-
-
-
-
`tests/`
Creation Workflow
Step 1: Validate Inputs
// Validate rule name (lowercase, hyphens only)const ruleName = args.name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
// Validate content is not emptyif (!args.content || args.content.trim().length === 0) {
thrownewError('Rule content cannot be empty');
}
Step 2: Create Rule File
const rulePath = `.claude/rules/${ruleName}.md`;
// Format content as markdownconst content = args.content.startsWith('#')
? args.content
: `# ${ruleName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase())}\n\n${args.content}`;
awaitwriteFile(rulePath, content);
Mandatory: Register in index
pnpm index-rules
Verify total_rules count increased. Rule is invisible to agents until indexed.
Step 3: Verify Auto-Discovery
Rules in .claude/rules/ are automatically loaded by Claude Code. No manual registration needed.
// Verify file was createdconst fileExists = awaitexists(rulePath);
if (!fileExists) {
thrownewError('Rule file creation failed');
}
Skill({
skill: 'rule-creator',
args: `--name code-standards --content "# Code Standards
## Organization
- Prefer small, cohesive files over large ones
- Keep interfaces narrow; separate concerns by feature
## Style
- Favor immutability; avoid in-place mutation
- Validate inputs and handle errors explicitly"`,
});
Create Git Workflow Rule
Skill({
skill: 'rule-creator',
args: `--name git-workflow --content "# Git Workflow
## Commit Guidelines
- Keep changes scoped and reviewable
- Use conventional commits: feat:, fix:, refactor:, docs:, chore:
## Branch Workflow
- Create feature branches from main
- Never force-push to main/master"`,
});
Related Skills
skill-creator - Create detailed workflows (for complex guidance needing a full SKILL.md)
hook-creator - Create enforcement hooks that accompany governance rules
Iron Laws
Every artifact MUST have a companion schema — Rules without a schema have no contract for structured validation. Create a JSON schema in .claude/schemas/ if the rule produces structured output or has configurable parameters.
Every artifact MUST be wired to at least one agent — A rule not referenced by any agent or skill is orphaned. Verify the rule is relevant to at least one agent's context (rules in .claude/rules/ are auto-loaded, but domain-specific rules should be referenced in agent prompts).
Every artifact MUST be indexed in its catalog — Rules not tracked in the catalog are hard to discover and audit. Add an entry or verify presence in the appropriate catalog.
Every artifact MUST pass integration validation — Run node .claude/tools/cli/validate-integration.cjs <rule-path> before marking creation complete. A rule that fails validation may have broken references or conflicts.
Every artifact MUST record a memory entry — Write the rule creation pattern, decisions, and any issues to .claude/context/memory/ (learnings.md, decisions.md, issues.md). Without memory, the creation is invisible to future sessions.
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md
After completing:
New rule pattern → .claude/context/memory/learnings.md
Search arXiv for academic research (mandatory for AI/ML, agents, evaluation, orchestration, memory/RAG, security):
Via Exa: mcp__Exa__web_search_exa({ query: 'site:arxiv.org <topic> 2024 2025' })
Direct API: WebFetch({ url: 'https://arxiv.org/search/?query=<topic>&searchtype=all&start=0' })
Record decisions, constraints, and non-goals in artifact references/docs.
Keep updates minimal and avoid overengineering.
arXiv is mandatory (not fallback) when topic involves: AI agents, LLM evaluation, orchestration, memory/RAG, security, static analysis, or any emerging methodology.
Regression-Safe Delivery
Follow strict RED -> GREEN -> REFACTOR for behavior changes.
Run targeted tests for changed modules.
Run lint/format on changed files.
Keep commits scoped by concern (logic/docs/generated artifacts).
