codingbuddy-rules

Common AI Coding Rules System

This directory contains shared coding rules and guidelines used across multiple AI coding assistants (Cursor, Claude Code, Codex, Antigravity, Amazon Q, Kiro, etc.) for consistent development practices.

Directory Structure

.ai-rules/
├── README.md              # This file - overview and usage guide
├── rules/                 # Common coding rules (AI-agnostic)
│   ├── core.md           # Workflow modes (PLAN/ACT/EVAL), communication
│   ├── clarification-guide.md  # Clarification Phase guidelines for PLAN mode
│   ├── project.md        # Tech stack, architecture, project context
│   └── augmented-coding.md  # TDD principles, code quality standards
├── agents/                # Specialist agent definitions (JSON)
│   └── *.json            # Domain specialist agents
└── adapters/              # AI tool-specific integration guides
    └── *.md              # Integration guides per tool

Purpose

Single Source of Truth

All AI coding assistants share the same:

• Workflow modes (PLAN/ACT/EVAL)
• Code quality standards (TDD, SOLID, 90%+ test coverage)
• Project context (tech stack, architecture, conventions)
• Specialist knowledge (security, performance, accessibility, etc.)

Benefits

• Consistency: All AI tools follow identical coding standards
• Maintainability: Update rules once, all tools benefit
• Extensibility: Easy to add new AI tools
• Flexibility: Tool-specific customizations via adapters
• Team Alignment: Everyone uses the same guidelines regardless of AI tool preference

Core Rules Overview

1. rules/core.md - Workflow & Communication

Workflow Modes:

• PLAN: Define implementation plan (includes optional Clarification Phase)
• ACT: Execute the plan and make code changes
• EVAL: Analyze results and propose improvements

Clarification Phase (Optional in PLAN):

• Triggers when AI detects ambiguous requirements (2+ unclear items)
• Sequential Q&A with progress indicator (Question N/M)
• Multiple-choice questions preferred for easy response
• See rules/clarification-guide.md for detailed guidelines

Key Principles:

• Start in PLAN mode by default
• Move to ACT when user types ACT
• Return to PLAN after ACT completes (automatic)
• Enter EVAL only when explicitly requested

2. rules/project.md - Project Setup

Purpose: Define project-specific context that AI assistants need.

Contents (customize per project):

• Tech stack and dependencies
• Project structure and architecture
• Development rules and conventions
• Code review checklist

Note: This file is a template. Each project should customize it based on their tech stack and architecture.

3. rules/augmented-coding.md - TDD & Quality

TDD Cycle:

• Red: Write failing test
• Green: Implement minimal code
• Refactor: Improve after tests pass

Code Quality:

• SOLID principles
• DRY (Don't Repeat Yourself)
• No mocking - test real behavior
• TypeScript strict mode (no any)
• Tidy First approach (separate structural vs behavioral changes)

Specialist Agents

Specialist agents provide domain-specific expertise:

Agent	Expertise	Use Cases
Code Reviewer	Quality evaluation, architecture	Code review, production readiness
Architecture Specialist	Layer boundaries, dependencies	System design, refactoring
Test Strategy Specialist	Test coverage, TDD workflow	Testing strategy, quality assurance
Performance Specialist	Optimization, profiling	Performance tuning, bottleneck analysis
Security Specialist	Authentication, vulnerabilities	Security audit, secure coding
Accessibility Specialist	WCAG 2.1 AA, ARIA	A11y compliance, screen readers
Documentation Specialist	Technical writing, clarity	Documentation quality
Code Quality Specialist	SOLID, DRY, complexity	Code quality planning/review
DevOps Engineer	CI/CD, containerization, monitoring	Infrastructure, deployment

See agents/README.md for detailed agent documentation.

AI Tool Integration

Each AI tool has its own integration guide in adapters/:

• Cursor: adapters/cursor.md
• Claude Code: adapters/claude-code.md
• GitHub Copilot / Codex: adapters/codex.md
• Antigravity: adapters/antigravity.md
• Amazon Q: adapters/q.md
• Kiro: adapters/kiro.md

Getting Started

For New AI Tool

• Read the adapter guide: Check if your tool has a guide in adapters/
• Create tool directory: e.g., .{tool}/rules/
• Reference common rules: Link to .ai-rules/ in your tool's config
• Add tool-specific customizations: Only what's unique to that tool

For Existing Tools

• Update existing configs: Add references to .ai-rules/
• Remove duplicates: Rely on common rules first
• Keep tool-specific features: Maintain what's unique to each tool

Usage Examples

Workflow Example

User: Create a new feature for user registration

AI: # Mode: PLAN
    [References .ai-rules/rules/core.md workflow]
    [Uses .ai-rules/rules/project.md context]
    [Applies .ai-rules/rules/augmented-coding.md TDD]

User: ACT

AI: # Mode: ACT
    [Executes implementation]

User: EVAL

AI: # Mode: EVAL
    [Evaluates with code-reviewer.json framework]

Referencing Rules

In any AI tool:

• @.ai-rules/rules/core.md - Workflow guidance
• @.ai-rules/rules/project.md - Project context
• @.ai-rules/agents/*.json - Specialist expertise

Maintenance

Updating Rules

For changes affecting all AI tools:

• Edit files in .ai-rules/rules/ or .ai-rules/agents/
• Commit changes
• All AI tools automatically use updated rules

For tool-specific changes:

• Edit only that tool's config (e.g., .cursor/rules/)
• Common rules remain unchanged

Update Checklist

After modifying .ai-rules/:

• Rules are AI-agnostic (no tool-specific syntax)
• Rules are technology-agnostic (no framework-specific content)
• All markdown files are valid
• Agent JSON files are valid
• Documentation updated if needed

Architecture Principles

Design Decisions

• AI-Agnostic Format: Use standard markdown and JSON
• Technology-Agnostic: No framework-specific examples in common rules
• Modular Structure: Separate concerns (workflow, project, quality)
• Tool Adapters: Each tool translates common rules to its format
• Single Source of Truth: .ai-rules/ is authoritative

Override Hierarchy

When rules conflict between common rules and tool-specific configurations:

Priority Order (highest to lowest):

• Tool-specific rules (e.g., .cursor/rules/)
• Common rules (.ai-rules/rules/*.md)
• Default AI behavior (tool's built-in defaults)

File Format Choices

• Markdown (.md): Universal, readable, supported by all tools
• JSON (.json): Structured data for agent definitions
• Tool-specific: Each tool keeps its native format

Contributing

Adding New Rules

• Determine scope: All tools or tool-specific?
• If all tools: Add to .ai-rules/rules/
• If tool-specific: Add to .{tool}/rules/
• Ensure content is technology-agnostic
• Update relevant documentation

Adding New AI Tools

• Create directory: .{new-tool}/
• Create adapter guide: .ai-rules/adapters/{new-tool}.md
• Create tool config: .{new-tool}/rules/
• Reference common rules from .ai-rules/
• Document tool-specific features

Further Reading

• Workflow Details: rules/core.md
• Clarification Phase: rules/clarification-guide.md
• Project Setup: rules/project.md
• TDD & Quality: rules/augmented-coding.md
• Agent System: agents/README.md
• Tool Integration: adapters/*.md