AI Rules Configuration

🤖 Purpose: Configure AI assistants with project-specific rules for consistent guidance

Quick Setup

1. Nothing to Copy — the Rules Ship Committed

The template ships a layered AI constitution at the project root:

• CLAUDE.md — the source of truth. Halt-on-violation rules for Claude Code, layered with .claude/engineering.md, .claude/workflow.md, and .claude/stack.md.
• AGENTS.md — a generated file for every tool that supports the AGENTS.md convention (VS Code + Copilot, Cursor, Cline, and others). Never edit it directly.

# Claude Code: nothing to do — CLAUDE.md and .claude/ are already committed
pnpm agents:build    # regenerate AGENTS.md after editing CLAUDE.md or .claude/*
pnpm agents:check    # verify AGENTS.md is in sync (runs in quality:ci)

If a tool expects its own filename instead of AGENTS.md, derive it rather than forking the content:

cp AGENTS.md .clinerules      # only if your tool predates AGENTS.md support

2. Customize Project Context

Edit CLAUDE.md to match your specific project, then regenerate:

# [Your Project Name]

Every time you choose to apply a rule(s), explicitly state the rule(s) in the output.

## Project Context
[Replace with your specific project description]
- Target audience: [your audience]
- Primary goals: [your goals]
- Key constraints: [your constraints]

pnpm agents:build

3. Configure AI Tool

For Claude Code:

• Rules files: CLAUDE.md + .claude/*.md
• Auto-detected at project root
• No additional configuration needed

For VS Code + Copilot, Cursor, and Cline:

• Rules file: AGENTS.md
• Auto-detected at project root
• Regenerate with pnpm agents:build after any CLAUDE.md/.claude/ edit

Astro-Specific Rules Included

The template includes pre-configured rules for:

Performance Standards

• Lighthouse ≥90 enforced in CI (mobile and desktop)
• JavaScript budget: <160KB
• CSS budget: <50KB
• Image optimization requirements

Technical Patterns

• Astro 6.x best practices
• Islands architecture guidance
• TypeScript strict mode
• Component hierarchy (atomic design)

Content Strategy

• Content Collections with Zod schemas
• MDX component patterns
• SEO optimization
• Accessibility (WCAG AA)

Customization Examples

B2B SaaS Website

## Project Context
Lead generation website for enterprise SaaS product
- Target: VPs and Directors at 200+ person companies
- Goal: 50 qualified leads per month
- Constraints: Must integrate with Salesforce CRM

Portfolio/Agency Site

## Project Context
Creative portfolio showcasing design work
- Target: Startup founders and marketing directors
- Goal: 5 premium project inquiries monthly
- Constraints: Heavy visual content, mobile-first

E-commerce Store

## Project Context
Performance-optimized e-commerce experience
- Target: Mobile-first shoppers, conversion focus
- Goal: <2s page load, >3% conversion rate
- Constraints: Large product catalog, international shipping

Advanced Configuration

IDE Integration

VS Code with GitHub Copilot:

Copilot reads AGENTS.md automatically. To pull additional docs into context:

.vscode/settings.json

{
  "github.copilot.advanced": {
    "contextFiles": [
      "AGENTS.md",
      "docs/ai-context/INDEX.md",
      "docs/PRD-*.md"
    ]
  }
}

Continue.dev:

.continue/config.json

{
  "contextProviders": [
    {
      "name": "docs",
      "params": {
        "folders": ["docs/ai-context/"]
      }
    }
  ]
}

Multiple AI Tools

Consistency is automatic: every tool reads either CLAUDE.md (Claude Code) or the AGENTS.md generated from it. The only rule is to treat CLAUDE.md and .claude/* as the single place you edit:

# After any rules edit
pnpm agents:build

# CI fails if AGENTS.md drifts from its sources
pnpm agents:check

Testing Your Configuration

Validation Prompts

Test your rules with these prompts:

"Based on our project rules, create a new component called ProductCard"

Should reference:

• Design tokens usage
• TypeScript interfaces
• Accessibility requirements
• Performance considerations

"Optimize the homepage for our target audience"

Should reference:

• Project-specific audience
• Conversion goals
• Performance budgets
• Brand guidelines

Rule Enforcement Check

Look for these patterns in AI responses:

• Rule References: “Following the [rule name] pattern…”
• Project Context: Mentions your specific audience/goals
• Constraint Awareness: Respects budgets and limitations
• Pattern Consistency: Uses established conventions

Maintenance

When to Update Rules

1. Project Evolution: Goals or audience change
2. New Patterns: Discovered better approaches
3. Tool Updates: AI assistant capabilities change
4. Team Feedback: Rules aren’t working effectively

Update Process

# 1. Edit the source of truth
# CLAUDE.md or .claude/*.md

# 2. Regenerate the cross-tool file
pnpm agents:build

# 3. Validate with your AI assistant
# Test key prompts

# 4. Commit both — agents:check gates drift in CI
git add CLAUDE.md .claude AGENTS.md

Version Control

CLAUDE.md, .claude/, and the generated AGENTS.md are committed — the agents:check drift gate depends on it. Don’t gitignore them.

Troubleshooting

Rules Not Applied

1. Check File Location: Must be at project root
2. Verify File Name: Exact spelling required
3. Restart AI Tool: May need to reload workspace
4. Test with Explicit Reference: “Following our project rules…”

Inconsistent Responses

1. Stale AGENTS.md: Run pnpm agents:build after editing CLAUDE.md
2. Review Rule Clarity: Avoid ambiguous language
3. Add Specific Examples: Show desired patterns
4. Remove Contradictions: Ensure rules don’t conflict

Performance Issues

1. Rule File Size: Keep under 2000 lines
2. Complex Logic: Simplify decision trees
3. Context Overload: Focus on essential guidance only

Remember: AI rules are most effective when they’re specific, actionable, and aligned with your actual development workflow.