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

Keywords

FAQs

What is codingbuddy-rules?

Is codingbuddy-rules well maintained?

Package last updated on 12 Apr 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

codingbuddy-rules

Common AI Coding Rules System

Directory Structure