Syntax Rules

Syntax Rules — Language-Specific Coding Standards

A two-layer rules engine: common universal principles + 18 language-specific extensions that override common defaults where idioms differ.

Architecture

references/
├── common/          # 10 universal rule files (ALWAYS loaded)
│   ├── agents.md              # Agent orchestration patterns
│   ├── code-review.md         # Review checklist, severity levels, workflow
│   ├── coding-style.md        # KISS/DRY/YAGNI, immutability, naming, file org
│   ├── development-workflow.md # Research -> Plan -> TDD -> Review -> Commit
│   ├── git-workflow.md        # Conventional commits, PR process
│   ├── hooks.md               # PreToolUse/PostToolUse/Stop hooks
│   ├── patterns.md            # Repository pattern, API response envelope
│   ├── performance.md         # Model selection, context window, extended thinking
│   ├── security.md            # Pre-commit checks, secret management, response protocol
│   └── testing.md             # 80% coverage, TDD (RED/GREEN/IMPROVE), AAA pattern
│
├── typescript/      # TS/JS: type safety, Zod validation, React props, Playwright E2E
├── angular/         # Angular: component patterns, RxJS, dependency injection
├── arkts/           # HarmonyOS/ArkTS: V2 state management, Navigation routing
├── cpp/             # C++: RAII, modern C++17/20/23, clang-format
├── csharp/          # C#: .NET conventions, async, nullable reference types
├── dart/            # Dart/Flutter: widget patterns, state management
├── fsharp/          # F#: functional idioms, computation expressions
├── golang/          # Go: interfaces, error wrapping, gofmt
├── java/            # Java: records, sealed types, Optional, streams
├── kotlin/          # Kotlin: null safety, sealed classes, coroutines, scope functions
├── perl/            # Perl: modern Perl patterns
├── php/             # PHP: PSR-12, strict types, readonly properties
├── python/          # Python: PEP 8, type annotations, pytest + FastAPI extension
├── rust/            # Rust: ownership, Result/?, thiserror/anyhow, iterators
├── swift/           # Swift: value semantics, Sendable, typed throws, actors
├── web/             # Web/Frontend: design quality, performance, accessibility
└── zh/              # Chinese translations of all common rules

When to Use

Workflow

Step 1: Detect Language

Identify the target language(s) from:

• File extensions (.ts, .py, .rs, .go, .java, .kt, .swift, .cpp, .cs, .php, .dart, .fs, .pl, .ets)
• Project config files (tsconfig.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Package.swift, CMakeLists.txt, composer.json, pubspec.yaml, .fsproj, angular.json)
• User-specified language

Step 2: Load Rules

Always load references/common/ (10 files) — these are universal non-negotiable principles.

Then load the matching language directory:

• Each language has 5 core files: coding-style.md, testing.md, patterns.md, security.md, hooks.md
• Python has an extra: fastapi.md
• Web has two extras: design-quality.md, performance.md

Priority: Language-specific rules override common rules when they conflict (specific > general).

Step 3: Apply Rules

Apply rules according to context:

When writing code:

1. Follow language coding-style.md for naming, formatting, immutability, error handling
2. Follow language patterns.md for idiomatic design patterns
3. Follow common/development-workflow.md for the implementation process
4. Validate input per common/coding-style.md and language security.md

When reviewing code:

1. Use common/code-review.md checklist (severity levels: CRITICAL/HIGH/MEDIUM/LOW)
2. Check security triggers from common/security.md
3. Apply language-specific style checks from language coding-style.md
4. Verify test coverage >= 80% per common/testing.md

When writing tests:

1. Follow TDD cycle from common/testing.md: RED -> GREEN -> IMPROVE
2. Use AAA pattern (Arrange-Act-Assert)
3. Apply language-specific test framework guidance from language testing.md
4. Target 80%+ coverage minimum

Step 4: Report Violations

When violations are found, report them using the severity framework from common/code-review.md:

Key Principles Summary

Immutability (CRITICAL — all languages)

• Create new objects, never mutate existing ones
• Language implementations: spread operator (TS), frozen dataclasses (Python), let by default (Rust/Swift), val (Kotlin), record (Java), Readonly<> (C#)

Security (CRITICAL — all languages)

• Never hardcode secrets
• Always validate input at system boundaries
• Use parameterized queries
• No console.log/print in production

Testing (MANDATORY — all languages)

• 80% minimum coverage
• TDD workflow: write test first, watch it fail, implement, refactor
• AAA pattern for test structure
• All three test types required: unit + integration + E2E

Error Handling (MANDATORY — all languages)

• Handle errors explicitly at every level
• Never silently swallow errors
• Use language-appropriate error types (Result, Either, exceptions, etc.)

File Organization (ALL languages)

• Many small files > few large files
• 200-400 lines typical, 800 max
• Organize by feature/domain, not by type

Multi-Language Projects

For projects using multiple languages (e.g., TypeScript frontend + Python backend):

1. Load common/ rules once
2. Load each language's rules independently
3. Apply each language's rules only to its respective files
4. Cross-cutting concerns (security, testing, git workflow) use common rules

Rebuttals