ai-coding-rules

AI Coding Rules

A comprehensive set of Go coding principles and Claude Code skills for building clean, maintainable, testable systems using linter-driven development.

What's Inside

📋 coding_rules.md

Complete Go coding principles covering:

• Type design (primitive obsession prevention, self-validating types)
• Architecture (vertical slices)
• Testing strategies (table-driven, real implementations over mocks)
• Refactoring patterns
• Anti-patterns to avoid

🛠️ skills/ - Claude Code Skills

Six specialized skills that work together to automate clean code practices:

1. linter-driven-development - Meta-orchestrator for complete workflow
2. code-designing - Domain type design and architecture planning
3. testing - Testing principles and patterns
4. refactoring - Linter-driven refactoring strategies
5. pre-commit-review - Design validation (advisory)
6. documentation - Feature documentation generation

Installation

Prerequisites

• Claude Code installed
• Go development environment

Install the Plugin

Step 1: Add the marketplace

/plugin marketplace add buzzdan/ai-coding-rules

Step 2: Install the plugin

/plugin install go-linter-driven-development@ai-coding-rules

Verify installation:

/plugin list

Should show: go-linter-driven-development (enabled)

That's it! All skills are now available:

• @linter-driven-development
• @code-designing
• @testing
• @refactoring
• @pre-commit-review
• @documentation

Optional: Load in CLAUDE.md

For automatic context loading:

# Your Project CLAUDE.md

## Automatic Go Coding Context
When working on Go code, ALWAYS read @ai-coding-rules/coding_rules.md first.

Skills Overview

🎯 Meta-Orchestrator

@linter-driven-development

The complete workflow orchestrator

Manages the entire development cycle:

• Phase 1: Design (invokes @code-designing if needed)
• Phase 2: Implementation (applies @testing principles)
• Phase 3: Linter loop (runs linter, invokes @refactoring if fails)
• Phase 4: Pre-commit review (invokes @pre-commit-review)
• Phase 5: Commit ready

Use when: Implementing any feature, bug fix, or refactor that should result in a commit.

🎨 Individual Skills

@code-designing

Domain type design and architecture planning

Helps you:

• Design self-validating types
• Prevent primitive obsession
• Plan vertical slice architecture
• Create proper type hierarchies

Use when: Planning new features or identifying need for new types.

@testing

Testing principles and patterns

Guides you on:

• Table-driven tests (cyclomatic complexity = 1)
• Testify suites (only for complex setup)
• Real implementations over mocks
• Synchronization without time.Sleep
• Coverage strategies (100% for leaf types)

Use when: Writing tests or clarifying testing approach.

@refactoring

Linter-driven refactoring patterns

Provides patterns for:

• Storifying (clarify abstraction levels)
• Extract type (fix primitive obsession)
• Early returns (reduce nesting)
• Switch extraction (categorize cases)
• Decision tree for complexity reduction

Use when: Linter fails or code feels complex.

@pre-commit-review

Design validation (advisory)

Validates code against design principles:

• 🔴 Design Debt - Will cause pain when extending
• 🟡 Readability Debt - Hard to understand now
• 🟢 Polish Opportunities - Minor improvements

Reviews entire commit + broader file context.

Use when: Before committing (automatically invoked by meta-orchestrator).

@documentation

Feature documentation generation

Creates documentation for:

• Problem & solution overview
• Architecture with design decisions
• Usage examples (basic + advanced)
• Testing strategy
• Integration points

Use when: After completing a feature (may span multiple commits).

Usage

Complete Workflow (Recommended)

Use the meta-orchestrator for automatic workflow management:

You: "Implement user authentication using @linter-driven-development"

Claude:
1. Designs UserID, Email types (@code-designing)
2. Implements with tests (@testing principles)
3. Runs linter, refactors if needed (@refactoring)
4. Reviews design (@pre-commit-review)
5. Presents commit-ready summary with findings

You decide:

• Commit as-is
• Fix design debt (🔴)
• Fix design + readability debt (🔴 + 🟡)
• Fix all findings (🔴 🟡 🟢)
• Refactor broader scope

Individual Skills

Invoke skills independently when needed:

"Use @code-designing to plan types for payment processing"
"Use @testing to structure tests for UserService"
"Use @refactoring to reduce complexity in HandleRequest"
"Use @pre-commit-review to validate this code"
"Use @documentation to document the auth feature"

The Linter-Driven Development Flow