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: | 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: ```yaml 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.