# Coding Rules

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

- Skill: `navraj007in/coding-rules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add navraj007in/coding-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/navraj007in/coding-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: navraj007in (https://skillmd.com/u/navraj007in)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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:
```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.