# AI Coding Standards

This directory contains coding standards and patterns for AI coding assistants.

## Structure

```
.ai/
├── README.md              # This file - overview of standards system
├── instructions.md        # General coding instructions and principles
├── .aiignore             # Files to exclude from AI context
├── context/              # Language and editor-specific documentation
│   ├── EDITORS.md        # LazyVim (preferred) and VSCode configuration
│   ├── AGENTS_GO.md      # Go patterns and best practices
│   ├── AGENTS_PYTHON.md  # Python patterns and best practices
│   ├── AGENTS_TYPESCRIPT_VUE.md  # TypeScript/Vue/Nuxt patterns
│   ├── AGENTS_POWERSHELL.md      # PowerShell and Azure automation
│   └── AGENTS_BASH.md    # Bash scripting patterns
└── prompts/              # Reusable prompts for common tasks
```

## For AI Assistants

When helping with code in this project:

1. **Read `instructions.md` first** - Contains general principles
2. **Read `context/EDITORS.md`** - For editor configuration (LazyVim preferred)
3. **Read relevant `context/AGENTS_*.md`** - For language-specific patterns
4. **Follow conventions strictly** - Use templates and examples from these files

## Quick Reference

| Language           | File                               | Key Patterns                                           |
| ------------------ | ---------------------------------- | ------------------------------------------------------ |
| **Go**             | `context/AGENTS_GO.md`             | Accept interfaces, return concrete; Functional options |
| **Python**         | `context/AGENTS_PYTHON.md`         | Type hints mandatory; Use uv                           |
| **TypeScript/Vue** | `context/AGENTS_TYPESCRIPT_VUE.md` | Composition API; Strict mode                           |
| **PowerShell**     | `context/AGENTS_POWERSHELL.md`     | Multi-sub by default; Graph API over loops             |
| **Bash**           | `context/AGENTS_BASH.md`           | Shellcheck; Proper error handling                      |
| **Editor**         | `context/EDITORS.md`               | LazyVim preferred; `<space>` leader                    |

## Tool Integration

All major AI coding assistants are configured to read from this directory:

- ✅ **Claude Code** - See `.clauderc` in project root
- ✅ **GitHub Copilot** - See `.github/copilot-instructions.md`
- ✅ **Cursor** - See `.cursorrules` in project root
- ✅ **Continue.dev** - See `.continuerc.json` in project root
- ✅ **Aider** - See `.aider.conf.yml` in project root

## Maintaining Standards

### Updating Patterns

1. Edit files in `.ai/context/` directory
2. Changes automatically apply to all AI tools
3. Commit changes to version control
4. Standards are shared across team

### Adding New Languages

1. Create `context/AGENTS_NEWLANG.md` following existing format
2. Update tool config files to include new file
3. Add to this README

### Custom Prompts

Add reusable prompts to `prompts/` directory:

- Code review templates
- Refactoring guides
- Testing strategies
- Architecture decisions

## For Developers

### First Time Setup

1. Review `instructions.md` for general principles
2. Read `context/EDITORS.md` to set up LazyVim
3. Read language-specific files for patterns
4. Configure your AI coding assistant (configs in project root)

### Daily Workflow

1. AI tools automatically read these standards
2. Follow patterns in code reviews
3. Update standards when patterns evolve
4. Share improvements with team

## Architecture Benefits

- ✅ **Single source of truth** - Edit once in `.ai/`, all tools see changes
- ✅ **DRY principle** - No duplication across config files
- ✅ **Tool agnostic** - Works with any AI assistant
- ✅ **Version controlled** - Standards tracked in git
- ✅ **Team shared** - Everyone uses same patterns
- ✅ **Discoverable** - Clear structure, easy to navigate