navraj007in/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:

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.