AI Code Standards

A Claude Code plugin that generates tailored engineering standards files (CLAUDE.md) for any project. Instead of copy-pasting rules or maintaining a monolithic config, it composes modular, opinionated fragments based on your stack, domain, team size, and compliance requirements.

Problem: AI coding assistants produce better code when given clear project-specific rules — but writing and maintaining those rules is tedious, error-prone, and rarely done well.

Solution: Auto-detect your stack, ask a short questionnaire, and assemble a comprehensive standards file from battle-tested fragments covering testing, security, code review, git hygiene, and more.

How It Works

1. Auto-detects your stack from manifest files (package.json, build.gradle, go.mod, Cargo.toml, etc.)
2. Asks a short questionnaire for what can't be inferred (team size, domain, compliance needs)
3. Composes modular fragments into a single, tailored standards file
4. Merges non-destructively with any existing standards — never overwrites your additions

Supported Stacks

Language	Build Tool	Testing Fragment
Java	Gradle	JaCoCo coverage, SpotBugs, OWASP dependency check
Go	go build	go test, cargo-llvm-cov/tarpaulin, gosec, govulncheck
Python	pip	pytest, coverage.py, bandit, pip-audit, mypy
TypeScript/JavaScript	npm	Vitest/Jest, c8/v8, eslint-plugin-security
Rust	cargo	cargo test, cargo-llvm-cov/tarpaulin, clippy, cargo audit

Frontend Frameworks

Framework	Testing Fragment
React / Next.js	React Testing Library, MSW, Storybook
Vue / Nuxt	Vue Test Utils, Testing Library for Vue, Pinia, Storybook
Shared	Playwright E2E, visual regression, axe-core a11y, Lighthouse CI

Multi-Stack Projects

Full-stack projects (e.g., Go + React, Java + Vue) are fully supported. Each stack gets its own testing and SAST fragments, and the generated file covers both.

What's Included

Every generated standards file includes these sections:

Section	What it covers
Honesty & Uncertainty	No fabrication, verify before answering, admit uncertainty
Boundaries	Hard "never do" rules — destructive ops, security, scope creep, dependency safety
Plan, Act, Reflect	When to plan first, approval gates, post-action sanity check
Testing Standards	Coverage gates, testing types, per-stack commands and config
Code Review Gate	Self-review checklist, AI code review, security scan, peer review
Security Scanning	Secrets detection, SAST, SCA, input validation, auth rules
Git Hygiene	Conventional Commits, atomic commits, branch strategy, PR rules
Definition of Done	Checklist that blocks "done" until all gates pass

Optional Sections (based on your inputs)

Section	When included
Regulated Data	PII, PHI, PCI, or government data handling
Accessibility	UI-facing projects (WCAG 2.1 AA)
Data Privacy	Projects handling PII or PHI
Solo Guardrails	Relaxed process rules for solo developers
Team Guardrails	Branch protection, CODEOWNERS, communication rules

Installation

Claude Code (via marketplace)

Two-step install inside Claude Code — add the marketplace, then install the plugin:

/plugin marketplace add brandonm/ai-code-standards
/plugin install code-standards@code-standards

The CLI equivalent (outside an interactive session) is:

claude plugin marketplace add brandonm/ai-code-standards
claude plugin install code-standards@code-standards

Manual (standalone skill, no plugin install)

If you'd rather just drop the skill into your ~/.claude/skills/ directory and skip the plugin namespace:

git clone https://github.com/brandonm/ai-code-standards.git
mkdir -p ~/.claude/skills
cp -r ai-code-standards/skills/generating-code-standards ~/.claude/skills/generating-code-standards

Standalone, the skill is available as /generating-code-standards (no plugin prefix).

Local development

To test the plugin without installing, run Claude Code with --plugin-dir:

claude --plugin-dir /path/to/ai-code-standards

Usage

Once installed as a plugin, invoke the skill in Claude Code:

/code-standards:generating-code-standards

Or ask naturally — the description triggers it without typing the slash command:

"Generate engineering standards for this project" "Create a CLAUDE.md for this repo" "Set up project standards"

The skill will:

1. Auto-detect your stack from manifest files
2. Ask you to confirm and fill in missing details
3. Generate a tailored standards file
4. Show you the output for review before writing

Project Structure

.claude-plugin/
  plugin.json                      # Plugin manifest (name, version, metadata)
  marketplace.json                 # Marketplace catalog listing this plugin
skills/
  generating-code-standards/
    SKILL.md                       # Skill entry point and workflow
    questionnaire.md               # Questions to gather inputs
    template.md                    # Assembly skeleton with conditionals
    fragments/
      honesty.md                   # Uncertainty protocol
      boundaries.md                # Do-not-do list
      boundaries-solo.md           # Relaxed rules for solo devs
      boundaries-team.md           # Stricter rules for teams
      testing-universal.md         # Testing philosophy and gates
      testing-java-gradle.md       # JaCoCo, Gradle commands
      testing-go.md                # go test, coverage
      testing-python.md            # pytest, coverage.py
      testing-node.md              # Vitest/Jest, c8
      testing-rust.md              # cargo test, llvm-cov
      testing-frontend.md          # Playwright, visual regression, a11y
      testing-react.md             # React Testing Library, MSW
      testing-vue.md               # Vue Test Utils, Pinia
      review-gate.md               # Self-review + AI review checklist
      security-generic.md          # Secrets, SAST, SCA, auth
      security-regulated.md        # PII/PHI/PCI additions
      plan-act-reflect.md          # Workflow for non-trivial changes
      git-hygiene.md               # Commit and branch conventions
      ui-accessibility.md          # WCAG 2.1 AA rules
      data-privacy.md              # Data handling and retention
    examples/
      java-gradle-backend.md       # Single-stack backend example
      java-react-fullstack.md      # Multi-stack full-stack example
      python-data-pipeline.md      # Solo dev, data pipeline example
      typescript-react-app.md      # Frontend web app example

Extending

Adding a new stack

1. Create a new fragment at fragments/testing-<language>.md
2. Use <!-- tier: project --> and <!-- requires: testing-universal -->
3. Include: test commands, coverage commands, report locations, test organization, SAST tools
4. Add the fragment to the selection matrix in SKILL.md
5. Add a conditional to template.md

Adding a new domain

1. Create a new fragment at fragments/<domain>.md
2. Add a question to questionnaire.md to trigger inclusion
3. Add a conditional to template.md

Modifying rules

Each fragment is standalone and order-independent. Edit any fragment directly — changes apply to all future generations. Existing generated files are not affected until regenerated.

Architecture

The plugin uses a fragment composition pattern — each concern (testing, security, accessibility, etc.) lives in its own standalone Markdown fragment with metadata headers for tier and dependencies. At generation time, fragments are selected based on detected stack and user inputs, then assembled via a template with variable substitution. This keeps each fragment independently editable and testable without affecting others.

Design principles:

• Simple, explicit, boring — no clever meta-logic, mostly substitution and concatenation
• Composable fragments — standalone, order-independent, each works if included alone
• Detect before asking — auto-detect what we can from manifest files, confirm with the user
• Never clobber — always diff/merge with existing files, preserving user additions
• Verified commands only — every CLI command in a fragment is validated against real tool docs
• Include "why" comments — every rule explains its rationale to prevent cargo-culting

Contributing

Contributions welcome. If you add a stack, domain, or improve an existing fragment:

1. Follow the existing fragment format (tier marker, requires marker, WHY comments)
2. Keep fragments under 50 lines where possible
3. Include only verified, real commands — no hallucinated flags
4. Add or update an example showing the fragment in context

License

MIT