# Coding Principles

Language-agnostic coding principles for maintainability, readability, and quality.

- Repository: https://github.com/shinpr/claude-code-workflows (708 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add shinpr/claude-code-workflows --skill coding-principles -g -a claude-code -y`
Codex: `npx skills add shinpr/claude-code-workflows --skill coding-principles -g -a codex -y`
Cursor: `npx skills add shinpr/claude-code-workflows --skill coding-principles -g -a cursor -y`
Gemini CLI: `npx skills add shinpr/claude-code-workflows --skill coding-principles -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add shinpr/claude-code-workflows`

## Description

Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Language-Agnostic Coding Principles

## Core Philosophy

1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity
2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle)
3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first.
4. **Explicit over Implicit**: Make intentions clear through code structure and naming
5. **Delete over Comment**: Remove unused code instead of commenting it out

## Code Quality

### Continuous Improvement
- Refactor related code inside the accepted outcome and governing boundaries when it reduces the change's risk or maintenance cost
- Improve code structure incrementally
- Keep the codebase lean and focused
- Delete code proven obsolete by the requested change after checking its callers; report uncertain or out-of-scope cleanup separately

### Readability
- Use meaningful, descriptive names drawn from the problem domain
- Use full words in names; abbreviations are acceptable only when widely recognized in the domain
- Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)
- Extract magic numbers and strings into named constants
- Keep code self-documenting where possible

## Function Design

### Parameter Management
- Group related positional parameters into an object, struct, or dictionary when call-site clarity or coordinated evolution requires it. Retain positional parameters when their order is conventional and the call remains clear, or an external/public signature requires them
- Preserve external/public signatures unless their migration is part of the accepted outcome or governing artifact

The rest: https://github.com/shinpr/claude-code-workflows/blob/HEAD/dev-skills/skills/coding-principles/SKILL.md