ai-rules-layeddie

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# ai-rules

**Standards-based AI rules for Elixir/BEAM development**

`ai-rules` is a reusable operating layer for AI-assisted Elixir/BEAM development. It gives coding agents a subscription-free, tool-agnostic set of rules, roles, skills, patterns, templates, and workflow configs so they can plan, build, and review projects consistently across OpenCode, Claude, Cursor, and local or MCP-based tooling.

# Disclaimer

This project is provided as-is and without any warranty. The authors are not responsible for any damages or losses resulting from the use of this project.
This repository has evolved through several iterations across multiple models and tools. Some documents may still reflect older assumptions and are being consolidated toward the positioning described above.

---

## 🎯 Objective

Create a **subscription-free**, standards-based starting point for Elixir/BEAM projects that works with:

- OpenCode (primary tool) - Multi-session agentic development
- Compatible tools (Claude Code, Cursor)
- Local LLMs (Ollama, LM Studio, MLX for Apple Silicon)
- MCP support (Serena)

**Key Principles**:

- Tool-agnostic: Guidelines work across OpenCode, Claude, Cursor
- Subscription-free: All tools (mgrep, Serena) are open-source and free
- Multi-session: Separate plan, build, and review workflows
- Flexible LLMs: Support for local + API providers
- Elixir/BEAM focused: OTP patterns, Domain Resource Action, TDD

---

## 📁 Directory Structure (AI-Search Friendly, Single Responsibility)

```
.
├── ai-rules/               # This repo (symlink in generated projects)
├── .opencode/              # Plan/Build/Review configs
├── config/                 # Environment config only (no business logic)
├── lib/
│   ├── [app]/              # Elixir runtime entry + supervision
│   │   ├── application.ex  # Top-level supervisor
│   │   ├── registry/       # Registry + DynamicSupervisor
│   │   └── support/        # Pure helpers (no IO/side effects)
│   └── [app]_ash/          # Ash Domain Resource Action (Elixir‑Scribe style)
│       ├── domains/        # Domain boundaries
│       │   └── accounts/
│       │       ├── resources/      # Ash Resources (schema + validations)
│       │       ├── actions/        # Ash Actions (single responsibility)
│       │       ├── policies/       # Authorization per resource
│       │       └── notifiers/      # Side-effect handlers (email, pubsub)
│       └── apis/            # Ash APIs that expose resources per domain
├── lib/[app]_web/          # Phoenix LiveView (thin controllers, state in Ash)
│   ├── endpoint.ex
│   ├── router.ex
│   ├── live/               # LiveViews / components
│   └── controllers/        # Minimal glue, delegate to Ash actions
├── priv/repo/              # Migrations & seeds
├── test/                   # Mirrors lib/ for easy grep & coverage
│   ├── support/            # DataCase/ConnCase factories
│   ├── ash/                # Resource/action tests (unit, property-based)
│   └── web/                # LiveView/Controller integration tests
├── flake.nix               # Nix devshell (phoenix_ash/universal/nerves)
└── project_requirements.md # Project + model/tool choices
```

**Why this layout?**
- Single Responsibility: Ash resources/actions/policies separated; controllers stay thin.
- Searchable: Domains/resources/actions live under predictable paths for mgrep/rg.
- Testable: `test/` mirrors `lib/` so coverage tools and agents find pairs quickly.

## 🧠 Default AI Persona
- **BEAMAI** (roles/beamai.md): Senior BEAM/Phoenix/Ash/Nerves/Nix expert with concise professional tone; use as default voice unless overridden by a role.

## 📑 Quickstart (Agents)
- See `docs/quickstart-agents.md` for mode commands, directory map, and preflight checks.

---

## 🚀 Quick Start

```bash
# Clone or symlink ai-rules into your project
cd my_new_project
ln -s ~/path/to/ai-rules ai-rules

# Initialize project
bash ai-rules/scripts/init_project.sh my_app

# Start plan session (Terminal 1)
opencode --config .opencode/opencode.plan.json

# Start build session (Terminal 2)
opencode --config .opencode/opencode.build.json
```

---

## 📋 Supported Tools

### OpenCode (Primary)

- **Multi-Session**: Plan, build, review workflows
- **MCP Support**: Serena MCP integration
- **mgrep Integration**: Native semantic search
- **Local LLMs**: Ollama, LM Studio, MLX for Apple Silicon

### Compatible Tools

- **Claude**: Full agent, skills, commands support
- **Cursor**: .cursorrules-based prompting

### Optional Retrieval Sidecar

- **Arcana (optional)**: Local document retrieval sidecar for all agents (not OpenCode-only)
- Setup/search scripts: `scripts/arcana_setup.sh`, `scripts/arcana_ingest_ai_rules_docs.sh`, `scripts/arcana_search_ai_rules_docs.sh`
- Guide: `docs/arcana-sidecar.md`

**Optional Claude bridge (opt-in)**  
- See `tools/claude/` for hooks/skills/templates tuned for Claude Code/Desktop.  
- User-copyable versions live in `templates/claude/`; nothing is auto-enabled for OpenCode.

**Reference snippets**  
- Elixir idioms and small code examples: `/Users/elay14/projects/2026/ai-rules/elixir_examples.md`

---

## 🎯 Elixir/BEAM Focus

- **OTP Patterns**: GenServer, Supervisor, Application, Registry
- **Domain Resource Action**: Organizes business logic into domains, resources, and actions
- **TDD Workflow**: Red-Green-Refactor cycle
- **Code Quality**: Credo, Dialyzer, formatting, type specs

---

## 🔧 Git Workflow

This project follows a strict Git workflow defined in `git_rules.md`:

- **Feature branch development**: Create branches for all changes
- **Pull requests for code review**: Use PRs for review before merging
- **Conventional commit messages**: Standardized commit format
- **Squash merging**: Clean history on main branch

### Git Roles & Skills

- **Git Specialist Role** (`roles/git-specialist.md`): Git and GitHub workflow expert
- **Git Workflow Skill** (`skills/git-workflow/SKILL.md`): Git automation and best practices

### Key Commands

```bash
# Create feature branch
git checkout -b feature/add-git-workflow

# Commit with conventional format
git add .
git commit -m "feat: add git workflow integration"

# Push and create PR
git push -u origin feature/add-git-workflow
gh pr create --title "Add git workflow" --body "Description..."

# Merge with squash
gh pr merge --squash

# Cleanup branches
git checkout main
git pull origin main
git branch -d feature/add-git-workflow
```

### Repositories

- **ai-rules**: https://github.com/layeddie/ai-rules
- **tensioner**: https://github.com/layeddie/tensioner

For detailed Git workflow rules, see `git_rules.md`.

---

## 🔧 Configuration

### OpenCode

- **Base config**: `tools/opencode/opencode.json`
- **Mode-specific**: Plan, build, review configs
- **MCP config**: `tools/opencode/opencode_mcp.json` (Serena)

### Claude

Compatible

- **Structure**: `.claude/` folder
- **Agents**: Role-based agents
- **Commands**: Slash commands (`/create-feature`, `/full-test`)
- **Skills**: Technical skills

### Cursor

- **Rules file**: `tools/cursor/.cursorrules` with agent prompts

### Nix (Optional)

- **Flake template**: `tools/nixos/flakes/universal.nix`
- **Integration**: MLX GPU support for M2 Max

---

## 📚 Roles

### Architecture & Planning

- **Architect** - System design, OTP supervision trees, domain boundaries
- **Orchestrator** - Implementation coordination, TDD workflow

### Domain-Specific

- **Backend Specialist** - API design, business logic, Ash resources
- **Frontend Specialist** - LiveView UI, real-time features
- **Database Architect** - Ecto schemas, query optimization, N+1 prevention

### Quality Assurance

- **QA** - Testing strategy, coverage analysis, property-based testing
- **Reviewer** - Code review, OTP best practices verification

---

## 🛠️ Technical Skills

### OTP Patterns

- **GenServer patterns** - Client/server separation, named processes
- **Supervisor strategies** - One-for-one, one-for-all, dynamic
- **Registry usage** - Dynamic process naming and discovery

### Ecto Query Analysis

- **N+1 prevention** - Preloading strategies, missing indexes, query optimization

### Test Generation

- **TDD workflow** - ExUnit, property-based testing (StreamData, PropCheck)

---

## 📋 Project Templates

### Phoenix + Ash + LiveView (Primary)

- Complete Phoenix web application
- Ash framework for domain modeling
- LiveView for real-time UI
- User authentication with Ash
- JSON API via Ash JSON API
- Real-time features via Phoenix PubSub

### Phoenix Basic (Stater)

- Basic Phoenix app
- Simple router and controller structure

### Elixir Library (Stater)

- OTP library with public API
- Clean module organization

### Nerves (Stater)

- Embedded Elixir for IoT devices
- Hardware-specific configurations

---

## ⚙️ Scripts

### init_project.sh

- **Purpose**: Initialize new Elixir project with AI rules
- **Functionality**: Creates directory structure, symlinks ai-rules, creates configs, generates .gitignore

### setup_opencode.sh

- **Purpose**: Setup OpenCode environment
- Installs mgrep, uv, Serena MCP
- **Functionality**: Validates all tools are available

### validate_requirements.sh

- **Purpose**: Validates project setup and requirements
- **Functionality**: Checks LLM config, Nix setup, dependencies, and OpenCode configs

---

## 🔨 Configuration Templates

### project_requirements.md

- **Purpose**: Starter brief for defining project goals, constraints, tool choices, architecture, and quality bar
- **Sections**: Project overview, technical stack, LLM/provider strategy, tool config, architecture, testing strategy

### opencode_mcp.json

- **Purpose**: MCP server configuration for ai-rules workflows

### mlx_gpu_config.yml

- **Purpose**: MLX GPU optimization for Apple Silicon M2 Max
- **Hardware**: 64GB RAM, 50GB VRAM, up to 5 GPUs

---

## 🎉 Best Practices

### OTP Principles

- Supervision trees with clear hierarchies
- Domain Resource Action pattern for business logic
- TDD workflow (Red, Green, Refactor)
- Code quality (Credo, Dialyzer, formatting)

### Anti-Patterns

- Blocking GenServer callbacks, mixing concerns, ignoring supervision strategies

---

## 🔗 Subscription-Free

All tools (mgrep, Serena) are open-source and free.

- No subscription required to use `ai-rules`.
- Local LLM providers (Ollama, LM Studio, MLX) are free.
- API providers are optional and user-chosen.

---

## 📖 Documentation

### Comprehensive guides for:

- Project initialization
- Tool-specific configurations
- Role definitions
- Technical skills
- Project templates
- Multi-session workflow
- Hardware optimization

---

## 🚀 Starting Point for New Elixir/BEAM Projects

**Use**: `ai-rules` as subscription-free starting point for:

- Standardized project structure
- Multi-session development workflow
- Comprehensive agent guidelines
- Tool integration (mgrep + Serena)
- Flexible LLM support (local + API)
- Elixir/BEAM best practices

**Perfect for**: full-stack web applications, libraries, and embedded systems.

---

## Attribution & Licensing

This repository includes ideas, patterns, and adaptation work informed by public Elixir/AI projects and docs.

- `claude-code-elixir` (George Guimarães): https://github.com/georgeguimaraes/claude-code-elixir
- `sagents` (Mark Ericksen): https://github.com/sagents-ai/sagents
- `usage_rules` (Ash Project): https://github.com/ash-project/usage_rules
- AgentJido ecosystem: https://github.com/agentjido

Where content is inspired or adapted, this repo prefers paraphrased integration over verbatim copying and follows upstream license terms (for example, Apache-2.0/MIT where applicable).

For local research/source inventory, see:
- `/Users/elay14/projects/2026/elixir-ai/Elixir-AI-Development-Environment-Outline.md`

ai-rules

Standards-based AI rules for Elixir/BEAM development

ai-rules is a reusable operating layer for AI-assisted Elixir/BEAM development. It gives coding agents a subscription-free, tool-agnostic set of rules, roles, skills, patterns, templates, and workflow configs so they can plan, build, and review projects consistently across OpenCode, Claude, Cursor, and local or MCP-based tooling.

Disclaimer

This project is provided as-is and without any warranty. The authors are not responsible for any damages or losses resulting from the use of this project. This repository has evolved through several iterations across multiple models and tools. Some documents may still reflect older assumptions and are being consolidated toward the positioning described above.

🎯 Objective

Create a subscription-free, standards-based starting point for Elixir/BEAM projects that works with:

OpenCode (primary tool) - Multi-session agentic development
Compatible tools (Claude Code, Cursor)
Local LLMs (Ollama, LM Studio, MLX for Apple Silicon)
MCP support (Serena)

Key Principles:

Tool-agnostic: Guidelines work across OpenCode, Claude, Cursor
Subscription-free: All tools (mgrep, Serena) are open-source and free
Multi-session: Separate plan, build, and review workflows
Flexible LLMs: Support for local + API providers
Elixir/BEAM focused: OTP patterns, Domain Resource Action, TDD

📁 Directory Structure (AI-Search Friendly, Single Responsibility)

.
├── ai-rules/               # This repo (symlink in generated projects)
├── .opencode/              # Plan/Build/Review configs
├── config/                 # Environment config only (no business logic)
├── lib/
│   ├── [app]/              # Elixir runtime entry + supervision
│   │   ├── application.ex  # Top-level supervisor
│   │   ├── registry/       # Registry + DynamicSupervisor
│   │   └── support/        # Pure helpers (no IO/side effects)
│   └── [app]_ash/          # Ash Domain Resource Action (Elixir‑Scribe style)
│       ├── domains/        # Domain boundaries
│       │   └── accounts/
│       │       ├── resources/      # Ash Resources (schema + validations)
│       │       ├── actions/        # Ash Actions (single responsibility)
│       │       ├── policies/       # Authorization per resource
│       │       └── notifiers/      # Side-effect handlers (email, pubsub)
│       └── apis/            # Ash APIs that expose resources per domain
├── lib/[app]_web/          # Phoenix LiveView (thin controllers, state in Ash)
│   ├── endpoint.ex
│   ├── router.ex
│   ├── live/               # LiveViews / components
│   └── controllers/        # Minimal glue, delegate to Ash actions
├── priv/repo/              # Migrations & seeds
├── test/                   # Mirrors lib/ for easy grep & coverage
│   ├── support/            # DataCase/ConnCase factories
│   ├── ash/                # Resource/action tests (unit, property-based)
│   └── web/                # LiveView/Controller integration tests
├── flake.nix               # Nix devshell (phoenix_ash/universal/nerves)
└── project_requirements.md # Project + model/tool choices

Why this layout?

Single Responsibility: Ash resources/actions/policies separated; controllers stay thin.
Searchable: Domains/resources/actions live under predictable paths for mgrep/rg.
Testable: test/ mirrors lib/ so coverage tools and agents find pairs quickly.

🧠 Default AI Persona

BEAMAI (roles/beamai.md): Senior BEAM/Phoenix/Ash/Nerves/Nix expert with concise professional tone; use as default voice unless overridden by a role.

📑 Quickstart (Agents)

See docs/quickstart-agents.md for mode commands, directory map, and preflight checks.

🚀 Quick Start

# Clone or symlink ai-rules into your project
cd my_new_project
ln -s ~/path/to/ai-rules ai-rules

# Initialize project
bash ai-rules/scripts/init_project.sh my_app

# Start plan session (Terminal 1)
opencode --config .opencode/opencode.plan.json

# Start build session (Terminal 2)
opencode --config .opencode/opencode.build.json

📋 Supported Tools

OpenCode (Primary)

Multi-Session: Plan, build, review workflows
MCP Support: Serena MCP integration
mgrep Integration: Native semantic search
Local LLMs: Ollama, LM Studio, MLX for Apple Silicon

Compatible Tools

Claude: Full agent, skills, commands support
Cursor: .cursorrules-based prompting

Optional Retrieval Sidecar

Arcana (optional): Local document retrieval sidecar for all agents (not OpenCode-only)
Setup/search scripts: scripts/arcana_setup.sh, scripts/arcana_ingest_ai_rules_docs.sh, scripts/arcana_search_ai_rules_docs.sh
Guide: docs/arcana-sidecar.md

Optional Claude bridge (opt-in)

See tools/claude/ for hooks/skills/templates tuned for Claude Code/Desktop.
User-copyable versions live in templates/claude/; nothing is auto-enabled for OpenCode.

Reference snippets

Elixir idioms and small code examples: /Users/elay14/projects/2026/ai-rules/elixir_examples.md

🎯 Elixir/BEAM Focus

OTP Patterns: GenServer, Supervisor, Application, Registry
Domain Resource Action: Organizes business logic into domains, resources, and actions
TDD Workflow: Red-Green-Refactor cycle
Code Quality: Credo, Dialyzer, formatting, type specs

🔧 Git Workflow

This project follows a strict Git workflow defined in git_rules.md:

Feature branch development: Create branches for all changes
Pull requests for code review: Use PRs for review before merging
Conventional commit messages: Standardized commit format
Squash merging: Clean history on main branch

Git Roles & Skills

Git Specialist Role (roles/git-specialist.md): Git and GitHub workflow expert
Git Workflow Skill (skills/git-workflow/SKILL.md): Git automation and best practices

Key Commands

# Create feature branch
git checkout -b feature/add-git-workflow

# Commit with conventional format
git add .
git commit -m "feat: add git workflow integration"

# Push and create PR
git push -u origin feature/add-git-workflow
gh pr create --title "Add git workflow" --body "Description..."

# Merge with squash
gh pr merge --squash

# Cleanup branches
git checkout main
git pull origin main
git branch -d feature/add-git-workflow

Repositories

ai-rules: https://github.com/layeddie/ai-rules
tensioner: https://github.com/layeddie/tensioner

For detailed Git workflow rules, see git_rules.md.

🔧 Configuration

OpenCode

Base config: tools/opencode/opencode.json
Mode-specific: Plan, build, review configs
MCP config: tools/opencode/opencode_mcp.json (Serena)

Claude

Compatible

Structure: .claude/ folder
Agents: Role-based agents
Commands: Slash commands (/create-feature, /full-test)
Skills: Technical skills

Cursor

Rules file: tools/cursor/.cursorrules with agent prompts

Nix (Optional)

Flake template: tools/nixos/flakes/universal.nix
Integration: MLX GPU support for M2 Max

📚 Roles

Architecture & Planning

Architect - System design, OTP supervision trees, domain boundaries
Orchestrator - Implementation coordination, TDD workflow

Domain-Specific

Backend Specialist - API design, business logic, Ash resources
Frontend Specialist - LiveView UI, real-time features
Database Architect - Ecto schemas, query optimization, N+1 prevention

Quality Assurance

QA - Testing strategy, coverage analysis, property-based testing
Reviewer - Code review, OTP best practices verification

🛠️ Technical Skills

OTP Patterns

GenServer patterns - Client/server separation, named processes
Supervisor strategies - One-for-one, one-for-all, dynamic
Registry usage - Dynamic process naming and discovery

Ecto Query Analysis

N+1 prevention - Preloading strategies, missing indexes, query optimization

Test Generation

TDD workflow - ExUnit, property-based testing (StreamData, PropCheck)

📋 Project Templates

Phoenix + Ash + LiveView (Primary)

Complete Phoenix web application
Ash framework for domain modeling
LiveView for real-time UI
User authentication with Ash
JSON API via Ash JSON API
Real-time features via Phoenix PubSub

Phoenix Basic (Stater)

Basic Phoenix app
Simple router and controller structure

Elixir Library (Stater)

OTP library with public API
Clean module organization

Nerves (Stater)

Embedded Elixir for IoT devices
Hardware-specific configurations

⚙️ Scripts

init_project.sh

Purpose: Initialize new Elixir project with AI rules
Functionality: Creates directory structure, symlinks ai-rules, creates configs, generates .gitignore

setup_opencode.sh

Purpose: Setup OpenCode environment
Installs mgrep, uv, Serena MCP
Functionality: Validates all tools are available

validate_requirements.sh

Purpose: Validates project setup and requirements
Functionality: Checks LLM config, Nix setup, dependencies, and OpenCode configs

🔨 Configuration Templates

project_requirements.md

Purpose: Starter brief for defining project goals, constraints, tool choices, architecture, and quality bar
Sections: Project overview, technical stack, LLM/provider strategy, tool config, architecture, testing strategy

opencode_mcp.json

Purpose: MCP server configuration for ai-rules workflows

mlx_gpu_config.yml

Purpose: MLX GPU optimization for Apple Silicon M2 Max
Hardware: 64GB RAM, 50GB VRAM, up to 5 GPUs

🎉 Best Practices

OTP Principles

Supervision trees with clear hierarchies
Domain Resource Action pattern for business logic
TDD workflow (Red, Green, Refactor)
Code quality (Credo, Dialyzer, formatting)

Anti-Patterns

Blocking GenServer callbacks, mixing concerns, ignoring supervision strategies

🔗 Subscription-Free

All tools (mgrep, Serena) are open-source and free.

No subscription required to use ai-rules.
Local LLM providers (Ollama, LM Studio, MLX) are free.
API providers are optional and user-chosen.

📖 Documentation

Comprehensive guides for:

Project initialization
Tool-specific configurations
Role definitions
Technical skills
Project templates
Multi-session workflow
Hardware optimization

🚀 Starting Point for New Elixir/BEAM Projects

Use: ai-rules as subscription-free starting point for:

Standardized project structure
Multi-session development workflow
Comprehensive agent guidelines
Tool integration (mgrep + Serena)
Flexible LLM support (local + API)
Elixir/BEAM best practices

Perfect for: full-stack web applications, libraries, and embedded systems.

Attribution & Licensing

This repository includes ideas, patterns, and adaptation work informed by public Elixir/AI projects and docs.

claude-code-elixir (George Guimarães): https://github.com/georgeguimaraes/claude-code-elixir
sagents (Mark Ericksen): https://github.com/sagents-ai/sagents
usage_rules (Ash Project): https://github.com/ash-project/usage_rules
AgentJido ecosystem: https://github.com/agentjido

Where content is inspired or adapted, this repo prefers paraphrased integration over verbatim copying and follows upstream license terms (for example, Apache-2.0/MIT where applicable).

For local research/source inventory, see:

/Users/elay14/projects/2026/elixir-ai/Elixir-AI-Development-Environment-Outline.md