coding-rules

name	coding-rules
description	Generate AI-consumable coding rules (CLAUDE.md, .cursorrules, copilot-instructions) and enforcement tooling from SDL

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:

Category	Source SDL Section	Example Rules
Architecture	architecture.style	Module boundary rules, service isolation, communication patterns
File Structure	architecture.projects	Framework conventions, ORM patterns, folder organization
Data Access	data	Repository pattern, database query rules, search engine usage
API Patterns	architecture.projects.backend	REST/GraphQL/gRPC conventions, versioning, service base paths
Authentication	auth	Provider-specific rules (Clerk/Auth0/Cognito), token handling, RBAC
Error Handling	errorHandling	Error format, global handler, circuit breaker, retry patterns
Integrations	integrations	Service client isolation, webhook handling, payment/email patterns
Testing	testing	Framework-specific rules, coverage targets, test structure
Observability	observability	Logging rules, tracing, metrics collection
Security	nonFunctional.security	PII handling, encryption, audit logging, OWASP compliance
Caching	data.cache	Cache invalidation, TTL, cache-aside pattern
Queues	data.queues	Message handling, idempotency, dead letter queues
Code Quality	(always generated)	SOLID principles, naming, DRY, single responsibility
Design Patterns	(always generated)	Framework-appropriate patterns (repository, factory, strategy)
File Size & Structure	(always generated)	Max file length, function complexity, extraction rules
API Design Quality	(always generated)	Pagination, filtering, consistent responses, HATEOAS
Database Queries	(always generated)	N+1 prevention, indexing, query optimization
Testing Quality	(always generated)	AAA pattern, test naming, mocking boundaries
Performance	(always generated)	Lazy loading, pagination, connection pooling
Import Organization	(always generated)	Import ordering, barrel exports, circular dependency prevention
Tech Debt Avoidance	(always generated)	TODO tracking, deprecation patterns, refactoring triggers
Resilience	(always generated)	Retry policies, timeouts, fallbacks, circuit breakers
Input Validation	(always generated)	Schema validation, sanitization, boundary validation
Concurrency	(always generated)	Race conditions, locking, atomic operations
Configuration	(always generated)	Env var patterns, secrets management, feature flags
Migration Safety	(always generated)	Backward compatibility, zero-downtime deploys, rollback
Documentation	(always generated)	When to document, inline comments, API docs
Git Workflow	(always generated)	Branch naming, commit messages, PR conventions

Conditional Categories (added when applicable)

Category	Condition	Rules
Accessibility	Frontend projects exist	WCAG compliance, ARIA, keyboard navigation, color contrast
State Management	Frontend projects exist	Framework-specific state rules (React Context, Redux, Zustand)
Mobile	Mobile projects exist	Platform guidelines, navigation, permissions, offline
Internationalization	Multiple regions defined	i18n patterns, locale handling, RTL support

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:

File	Purpose	Language
.eslintrc.sdl.js	Custom ESLint rules from architecture	TypeScript/JS
pyproject.sdl.toml	Ruff/flake8 config from architecture	Python
.golangci.sdl.yml	golangci-lint config from architecture	Go
.dependency-cruiser.sdl.cjs	Module boundary enforcement	TypeScript/JS
.lintstagedrc.sdl.json	Pre-commit hook config	All
tests/architecture.test.ts	Architecture conformance tests	TypeScript

---

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:

Framework	Tailored Rules
Node.js/Express	Middleware patterns, async/await error handling, route organization
Python/FastAPI	Pydantic models, dependency injection, async endpoints
Go	Interface-based design, error wrapping, goroutine safety
.NET 8	Controller patterns, DI container, middleware pipeline
Java/Spring	Bean lifecycle, AOP patterns, Spring Security
Next.js	App Router conventions, Server Components, RSC boundaries
React	Hook rules, component composition, render optimization

---

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:

Framework	Language	Configs Generated
nodejs	TypeScript	ESLint, dependency-cruiser, arch tests
nextjs, react, vue, angular, svelte	TypeScript	ESLint (with React hooks/a11y if applicable)
python-fastapi	Python	Ruff + Mypy config
go	Go	golangci-lint config
java-spring	Java	ArchUnit tests
dotnet-8	C#	NetArchTest tests

Files Produced

File	Language	Purpose
.eslintrc.sdl.js	TypeScript/JS	Custom ESLint rules from SDL architecture
pyproject.sdl.toml	Python	Ruff lint + Mypy strict + pytest coverage config
.golangci.sdl.yml	Go	16+ linters with complexity limits
.dependency-cruiser.sdl.cjs	TypeScript/JS	Module boundary enforcement (modular-monolith/microservices)
.lintstagedrc.sdl.json	All	Pre-commit hook command mapping
.husky/pre-commit	All	Git pre-commit hook script
__tests__/architecture.sdl.test.ts	TypeScript	Architecture conformance tests
src/test/java/architecture/ArchitectureTest.java	Java	ArchUnit architecture tests
tests/Architecture.Tests/ArchitectureTests.cs	.NET	NetArchTest architecture tests
.github/workflows/enforce-architecture.yml	All	CI gate workflow

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:

Rule	Severity	What It Prevents
no-circular	error	Circular dependencies
no-cross-module-internals	error	Importing another module's internal files (only .interface.ts and .types.ts allowed)
no-db-in-routes	error	Routes importing database directly
no-repository-in-routes	error	Routes bypassing services to access repositories
shared-no-module-imports	error	Shared utilities depending on business modules
orm-only-in-repositories-{name}	error	ORM package imported outside repository files

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:

Job	Steps
lint-typescript	npm ci → ESLint → dependency-cruiser → architecture tests
lint-python	pip install → ruff check → ruff format → mypy → pytest with coverage
lint-go	golangci-lint → go test with coverage threshold
lint-java	mvnw verify (includes ArchUnit)
lint-dotnet	dotnet restore → dotnet test Architecture.Tests
commit-lint	commitlint (conventional commits)

SDL Sections Used (Enforcement)

SDL Section	What It Controls
architecture.projects.backend[].framework	Which language configs to generate
architecture.projects.frontend[].framework	React hooks/a11y rules, TypeScript linting
architecture.style	Enables dependency-cruiser module boundary rules
architecture.services[]	Module names for cross-module import restrictions
architecture.projects.backend[].orm	ORM-specific import restrictions
testing.coverage.target	Coverage enforcement threshold in CI

Advisory vs. Enforcement

Aspect	Advisory rules (above)	Enforcement tooling (this section)
Output	CLAUDE.md, .cursorrules, copilot-instructions.md	ESLint, Ruff, golangci-lint, tests, CI
Enforcement	Advisory (AI tool reads them)	Hard gates (CI blocks violations)
Scope	27+ categories of architecture rules	Linting, boundaries, secrets, coverage
When	Always useful	When team needs CI-level enforcement

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