AI Agent Configuration for ANY Projects

A production-tested configuration for AI coding assistants (Claude Code, Cursor). This setup enforces a docs-first development pipeline, strict coding standards, and structured agent workflows.

What's Included

CLAUDE.md                          # Entry point -- loaded automatically every session
.claude/
├── settings.json                  # Plugin configuration (Serena, Context7)
├── mcp.example.json               # MCP server config template
├── agents/                        # Sub-agent definitions for parallel pipelines
│   ├── api-docs-author.md         # OpenAPI spec reconciliation
│   ├── code-architect.md          # Architecture design from codebase analysis
│   ├── code-explorer.md           # Deep codebase analysis and tracing
│   ├── code-implementer.md        # Isolated sub-task implementation
│   ├── code-reviewer.md           # Confidence-based code review
│   ├── docs-author.md             # Documentation reconciliation
│   └── test-author.md             # Test planning and authoring
├── commands/                      # Slash commands (workflow entry points)
│   ├── business.md                # /business -- BRD generation from client input
│   ├── cypress.md                 # /cypress -- E2E test generation
│   ├── documentation.md           # /documentation -- docs reconciliation
│   ├── feature.md                 # /feature -- full pipeline in one session
│   ├── implement.md               # /implement -- code from ready specs
│   ├── improvement.md             # /improvement -- change existing functionality
│   └── specification.md           # /specification -- technical spec from BRD
├── rules/                         # Coding rules (always or conditionally loaded)
│   ├── ai.md                      # MCP usage priority, token efficiency
│   ├── api.md                     # JSON API standards, DTOs, OpenAPI
│   ├── architecture.md            # Project structure, service naming
│   ├── bundles.md                 # Bundle registration protocol
│   ├── coding-standards.md        # PHP/Vue/Stimulus conventions
│   ├── datatable.md               # Admin table implementation
│   ├── documentation.md           # docs/ layout and update rules
│   ├── filters.md                 # Filter system (ORM/Elasticsearch)
│   ├── implementation-sequence.md # Build order for new features
│   ├── pr-and-debug.md            # Pre-PR checks, troubleshooting
│   └── workflow.md                # Docs-first pipeline definition
└── skills/                        # Context-triggered instruction sets
    ├── api/SKILL.md               # API endpoint implementation
    ├── bundle-feature/SKILL.md    # New bundle/entity creation
    ├── commit/SKILL.md            # Git commit message generation
    ├── cypress-tests/SKILL.md     # Cypress E2E test generation
    ├── datatable/SKILL.md         # Admin DataTable implementation
    ├── docs-sync/SKILL.md         # Code-vs-docs mismatch resolution
    ├── fixtures/SKILL.md          # Test data fixtures
    ├── grounded/SKILL.md          # Evidence-based reasoning gate
    ├── review/SKILL.md            # Code review checklist
    ├── security/SKILL.md          # Security and permissions checklist
    └── web-tests/SKILL.md         # Functional HTTP test authoring

docs/                              # Documentation structure (docs-first)
├── _templates/                    # Document templates for the pipeline
├── infrastructure/ai/            # AI setup documentation
├── architecture/                  # System-level architecture docs
├── bundles/                       # Per-bundle technical documentation
├── business/                      # Business Requirements Documents
├── design/                        # Business rules and user flows
└── testing/                       # Test strategy and guidance

The Pipeline

The core idea is docs-first development -- documentation is written before code and serves as the contract for implementation.

Client request --> BRD --> Design doc --> Feature spec --> Implementation --> Verification

Stage	Command	Input	Output
Business Analysis	/business	Client description	BRD with risks, questions, requirements
Technical Design	/specification	Approved BRD	Design doc + feature spec with sub-tasks
Implementation	/implement	BRD + design + spec	Code + tests + OpenAPI + docs reconciliation
Full Pipeline	/feature	Client description	All of the above in one session
Change Existing	/improvement	Change description	Delta analysis + updated docs + code
Verify Docs	/documentation	Optional scope	Compliance report

How to Use

1. Copy to your project

cp -r .claude/ /path/to/your/project/
cp CLAUDE.md /path/to/your/project/
cp -r docs/ /path/to/your/project/

2. Configure MCP servers

Copy .claude/mcp.example.json to your MCP client config and update the project path:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--project", "/path/to/your/project"]
    }
  }
}

3. Customize for your project

File	What to change
CLAUDE.md	Project name, tech stack description
.claude/rules/architecture.md	Your bundle/module structure, service naming
.claude/rules/coding-standards.md	Your PHP/JS conventions, linter levels
.claude/rules/api.md	Your API patterns, auth mechanism
.claude/skills/*/SKILL.md	Domain-specific patterns and checklists
docs/_templates/	Adjust template sections to your domain

4. Start using

Once configured, the AI assistant will automatically:

• Load CLAUDE.md as context entry point
• Apply rules from .claude/rules/ based on file globs
• Trigger skills from .claude/skills/ based on task context
• Use slash commands for structured workflows
• Launch sub-agents for parallel pipeline tasks

Key Concepts

Rules vs Skills vs Commands vs Agents

Concept	Loaded when	Purpose
Rules	Always (core) or by file glob (contextual)	Enforce project conventions and standards
Skills	Triggered by task context keywords	Provide domain-specific patterns and checklists
Commands	User invokes /command	Orchestrate multi-step workflows with gates
Agents	Launched by commands as sub-tasks	Execute focused work in parallel (review, test, docs)

MCP Priority Order

The AI uses context sources in priority order to minimize token usage:

1. Nexus MCP -- Docs vault (semantic search, read/write notes)
2. Serena MCP -- Code navigation (symbols, structure)
3. Fallback -- grep / file reads (when MCP is unavailable)
4. Context7 -- External library documentation

Requirements

• Claude Code or Cursor with Claude
• Serena MCP (code navigation)
• Context7 plugin (library docs)
• Optional: Nexus (docs vault integration)

License

MIT