Coding Rules

Coding Rules Generator

Generate architecture-aware coding rules that AI coding tools (Claude Code, Cursor, GitHub Copilot) enforce automatically across every session. Optionally generates hard enforcement tooling (ESLint, dependency-cruiser, pre-commit hooks, architecture tests).

Input: SDL document Output: CLAUDE.md, .cursorrules, .github/copilot-instructions.md, per-project CLAUDE.md, optional enforcement configs

What It Generates

Advisory Rules (CLAUDE.md / .cursorrules / copilot-instructions.md)

A single markdown file (output to 3 locations for tool coverage) containing architecture-derived coding rules organized by category:

Conditional Categories (added when applicable)

Per-Project Rules

For monorepo setups, generates {project-name}/CLAUDE.md with project-specific rules:

• Backend: framework conventions, API style, ORM patterns, port assignment
• Frontend: rendering mode, styling approach, component library, state management

Enforcement Tooling (Optional)

When coding-rules-enforcement is in artifacts.generate, produces hard gates:

How Rules Are Generated

Rules are deterministic — same SDL input always produces identical output. The generator:

1. Reads architecture style, projects, data layer, auth, integrations from SDL
2. Applies framework-specific rule templates (e.g., Express error handling vs FastAPI exception handlers)
3. Adds conditional categories based on project composition
4. Generates per-project overlays for monorepo setups
5. Renders all rules into a single markdown document

Framework-Aware Rules

The generator tailors rules to the specific tech stack:

When to Use

• After /architect:scaffold — generate rules that match the scaffolded project structure
• After SDL changes — regenerate to keep rules in sync with architecture evolution
• When onboarding AI tools — drop CLAUDE.md into any project for instant architecture awareness
• When adding enforcement — use coding-rules-enforcement artifact for CI/CD gates

Integration

The coding rules generator is available as an SDL artifact type:

artifacts:
  generate:
    - coding-rules              # Advisory rules (CLAUDE.md, .cursorrules, copilot-instructions)
    - coding-rules-enforcement  # Hard gates (ESLint, dependency-cruiser, pre-commit, arch tests)

Both are generated via the generate_from_sdl agent tool or the /api/sdl/generate endpoint.

Hard Enforcement Tooling

When coding-rules-enforcement is in artifacts.generate, the advisory rules above are backed by hard gates — linters, module boundary checks, architecture tests, pre-commit hooks, and a CI workflow. All configs are derived deterministically from the SDL document.

API: POST /api/sdl/generate with artifactType: "coding-rules-enforcement" (no dedicated route)

Language Detection

The generator inspects architecture.projects.backend[] and frontend[] frameworks to determine which configs to produce:

Files Produced

ESLint Rules (TypeScript/JS)

20+ rules enforced:

• @typescript-eslint/no-explicit-any: error — no any type
• max-params: 3 — max function parameters
• no-console: error (allow warn) — no console.log in production
• no-var, prefer-const — modern variable declarations
• no-magic-numbers: warn — avoid unlabeled constants
• max-depth: 3 — max nesting depth
• max-lines: 500 — max file size
• max-lines-per-function: 50 — max function length
• @typescript-eslint/consistent-type-imports — type-only imports
• import/no-cycle — no circular imports
• import/order — enforced import ordering
• @typescript-eslint/naming-convention — camelCase functions, PascalCase types, UPPER_CASE enums
• @typescript-eslint/no-floating-promises — no unhandled promises
• no-await-in-loop: warn — avoid sequential async in loops
• @typescript-eslint/no-unused-vars — no dead code

React-specific (when frontend uses React/Next.js):

• react-hooks/rules-of-hooks — hook call rules
• react-hooks/exhaustive-deps — dependency arrays
• jsx-a11y/* — accessibility rules (alt-text, valid anchors, key events, labels)

Dependency Cruiser Rules (Module Boundaries)

Generated when architecture.style is modular-monolith or microservices:

Architecture Tests

TypeScript (__tests__/architecture.sdl.test.ts):

• Module Boundaries: no module imports another module's repository or internal files
• Data Access Patterns: service files don't use database client directly; route files don't import repositories
• Security: no hardcoded secrets (Stripe keys, Anthropic keys, base64 keys)
• Dependency Graph: runs dependency-cruiser validation (modular-monolith/microservices)
• Coverage: validates coverage target from SDL testing.coverage.target

Java (ArchitectureTest.java with ArchUnit):

• Controllers don't access repositories
• Services don't depend on controllers
• Repositories don't depend on services
• No cyclic package dependencies
• Per-module internal access restrictions

.NET (ArchitectureTests.cs with NetArchTest):

• Controllers don't reference repositories
• Services don't depend on controllers
• Repositories don't depend on services

CI Workflow (.github/workflows/enforce-architecture.yml)

Runs on PR to main/develop and push to main. Jobs by language:

SDL Sections Used (Enforcement)

Advisory vs. Enforcement

Use advisory rules alone for AI-guided development; add coding-rules-enforcement in artifacts.generate for automated CI gates.