Coding standards, tooling configurations, and development workflows for deznode projects. This repository provides reusable documentation, configuration templates, and Claude Code rules for bootstrapping new projects.
| Layer | Technologies |
|---|---|
| Backend | Kotlin, Spring Boot 4, Spring Modulith 2.0, PostgreSQL, Flyway, Testcontainers |
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4, Zustand |
| Mobile | Kotlin Multiplatform, Jetpack Compose, SQLDelight, Koin, Ktor |
| Tooling | Taskfile v3, Lefthook, ESLint, Prettier, ktlint, detekt, EditorConfig |
| Infrastructure | Docker, Docker Compose, Terraform |
coding-standards/
├── docs/ # Standalone reference documentation
│ ├── backend/
│ │ └── 01-architecture.md # Spring Modulith architecture patterns
│ ├── frontend/
│ │ └── 01-architecture.md # Next.js App Router architecture
│ ├── mobile/
│ │ └── 01-architecture.md # KMP module layout and DDD for mobile
│ ├── tooling/
│ │ ├── 01-linting-formatting.md # ESLint, Prettier, ktlint, detekt
│ │ ├── 02-git-hooks.md # Lefthook pre-commit hooks
│ │ ├── 03-task-runner.md # Taskfile v3 setup
│ │ └── 04-editor-config.md # EditorConfig settings
│ ├── git/
│ │ └── 01-workflow.md # Commits, branches, PRs
│ └── testing/
│ └── 01-strategy.md # Testing philosophy and tiers
├── templates/
│ ├── claude-rules/ # Claude Code rules (.claude/rules/)
│ │ ├── backend/ # Backend-specific rules
│ │ ├── frontend/ # Frontend-specific rules
│ │ ├── mobile/ # Mobile/KMP-specific rules
│ │ └── infrastructure/ # Infrastructure rules
│ ├── configs/ # Configuration file templates
│ └── claude-hooks/ # Claude Code hooks (.claude/hooks/)
├── skills/ # Claude Code plugin skill
│ └── coding-standards/ # Bootstrap, update, audit skill
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
└── README.md # This file
Read these files for context and reference when working on any deznode project. Each document is self-contained and covers a specific concern (architecture, tooling, testing, git workflow).
Copy into a new project's .claude/rules/ directory to give Claude Code project-specific knowledge:
cp -r templates/claude-rules/* /path/to/project/.claude/rules/Copy and adapt configuration files for new projects:
cp templates/configs/.editorconfig /path/to/project/
cp templates/configs/lefthook.yml /path/to/project/
cp templates/configs/Taskfile.yml /path/to/project/Review and adjust paths, project names, and tool versions after copying.
Copy into a new project's .claude/hooks/ directory and configure in .claude/settings.json:
cp -r templates/claude-hooks/* /path/to/project/.claude/hooks/This repo is a Claude Code plugin with an automated skill for bootstrapping, updating, and auditing projects.
From the target project directory:
# Add this repo as a plugin marketplace
/plugin marketplace add /path/to/coding-standards
# Install the plugin
/plugin install coding-standards@coding-standardsThe skill triggers automatically when you mention "coding standards", "bootstrap rules", "update rules", or "audit standards". Or invoke directly:
/coding-standards:coding-standards
- Bootstrap -- First-time setup: detects your ecosystem (JVM/Node.js/KMP), copies relevant rules, configs, and hooks with path customization
- Update -- Syncs existing project with latest templates: shows diffs, lets you select which updates to apply
- Audit -- Read-only compliance check: scores your project against current standards, reports missing or outdated files
The skill is ecosystem-aware: JVM projects get backend rules, Node.js projects get frontend rules, KMP/Android projects get mobile rules, full-stack projects get everything.
If you prefer to copy templates manually instead of using the plugin:
-
Create the project repository and clone it locally.
-
Clone this repo alongside your project:
git clone https://github.com/deznode/coding-standards.git
-
Copy editor and tooling configs:
cp coding-standards/templates/configs/.editorconfig . cp coding-standards/templates/configs/lefthook.yml . cp coding-standards/templates/configs/Taskfile.yml .
-
Set up Claude Code rules:
mkdir -p .claude/rules cp -r coding-standards/templates/claude-rules/* .claude/rules/ -
Set up Claude Code hooks:
mkdir -p .claude/hooks cp -r coding-standards/templates/claude-hooks/* .claude/hooks/ -
Install git hooks:
lefthook install
-
Customize: Edit copied files to match your project's directory structure, module names, and tool versions.
-
Reference the docs: Use
docs/as a living reference for architecture decisions, coding patterns, and workflow conventions.
| Document | Description |
|---|---|
| Architecture | Spring Modulith module layout, DDD patterns, event-driven communication |
| API Design | ApiResult wrappers, controllers, HTTP patterns, validation |
| Kotlin Conventions | Jackson 3.x, kotlin-logging, transactions, naming conventions |
| Database Patterns | Flyway migrations, entities, UUID keys, JSONB, full-text search |
| Security | JWT authentication, authorization, rate limiting |
| Testing | Integration tests, MockMvc, MockK, Testcontainers, test fixtures |
| Error Handling | Sealed exception hierarchies, ProblemDetail (RFC 9457), ordered @ControllerAdvice |
| Document | Description |
|---|---|
| Architecture | Next.js App Router, server components, client islands, caching |
| Component Patterns | forwardRef, clsx, loading states, import organization |
| State Management | Zustand, TanStack Query, query key factories, Zod schemas |
| Styling | 3-tier token architecture, dark mode, Tailwind CSS 4 |
| API Client | Factory pattern, serverApi, client hooks, dual data fetching |
| Performance | Waterfalls, bundle size, server-side optimization, Suspense |
| Document | Description |
|---|---|
| Architecture | KMP module layout, source sets, DDD for mobile |
| Build Configuration | Convention plugins, version catalogs, Gradle config |
| Compose Patterns | Route/Screen split, state management, navigation, performance |
| Kotlin Conventions | Expect/actual, Koin DI, kotlinx-serialization, Ktor |
| Offline First | SQLDelight, sync strategies, outbox, conflict resolution |
| Testing | Testing pyramid, Compose tests, Flow tests, screenshot tests |
| Quality Tooling | Detekt, ktlint, Kover, ArchUnit for mobile |
| Document | Description |
|---|---|
| Linting and Formatting | ESLint, Prettier, ktlint, detekt configuration |
| Git Hooks | Lefthook pre-commit hook setup |
| Task Runner | Taskfile v3 standard tasks |
| Editor Config | EditorConfig cross-editor settings |
| Document | Description |
|---|---|
| Git Workflow | Conventional commits, branching, PR process |
| Testing Strategy | Testing philosophy, tiers, and commands |
| Directory | Description |
|---|---|
| Claude Rules | Claude Code rule files for .claude/rules/ |
| Config Templates | Reusable configuration files |
| Claude Hooks | Claude Code hook scripts |
Rules in the documentation use three severity levels to set expectations:
| Level | Meaning | Enforcement |
|---|---|---|
| MUST | Non-negotiable. Violations block PRs. | Automated (linter, CI gate, pre-commit hook) |
| SHOULD | Strong recommendation. Follow unless you have a documented reason not to. | Code review |
| MAY | Team preference. Use judgment based on context. | Informational |
Rules enforced by tooling (formatters, linters, CI) have near-100% compliance. Focus human attention on architecture, security, and correctness decisions.
Deviating from a standard is acceptable when:
- The rule doesn't apply to the specific context (e.g., a prototype, spike, or proof-of-concept).
- Following the rule would introduce worse problems (performance, readability, or maintainability).
- The rule conflicts with a third-party library or framework constraint.
How to document an exception:
- Add an inline comment explaining the deviation:
// Exception: [reason] - For architectural deviations, record an ADR (Architecture Decision Record).
- If the same exception recurs across multiple files, propose a rule change instead.
These standards are living documents. To propose a change:
- Open a PR against this repository with the proposed change.
- Include rationale — explain what problem the change solves or what improvement it brings.
- Reference evidence — link to incidents, code review discussions, or industry practices that support the change.
- Allow review time — changes affect all projects. Give the team at least one week to comment.
Changes that remove rules require the same rigor as adding them. Document why the rule is no longer needed.
Review this standard quarterly to:
- Remove rules that no longer provide value.
- Add rules based on recurring bugs, code review friction, or new tooling.
- Update version references (Spring Boot, Next.js, Tailwind, etc.) as the stack evolves.
- Incorporate feedback from developers using the standard.