# Coding Principles

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

- **Type:** Skill
- **Install:** `agentstack add skill-shinpr-claude-code-workflows-coding-principles`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shinpr](https://agentstack.voostack.com/s/shinpr)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shinpr](https://github.com/shinpr)
- **Source:** https://github.com/shinpr/claude-code-workflows/tree/main/dev-workflows-fullstack/skills/coding-principles

## Install

```sh
agentstack add skill-shinpr-claude-code-workflows-coding-principles
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point.
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 within each change set — address style, naming, or structure issues in the files being modified
- Improve code structure incrementally
- Keep the codebase lean and focused
- Delete unused code immediately

### 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
- **Recommended**: 0-2 parameters per function
- **For 3+ parameters**: Use objects, structs, or dictionaries to group related parameters
- **Example** (conceptual):
  ```
  // Instead of: createUser(name, email, age, city, country)
  // Use: createUser(userData)
  ```

### Single Responsibility
- Each function should do one thing well
- Keep functions small and focused (typically  micro-optimizations
- **Use appropriate data structures**: Choose based on access patterns
- **Resource management**: Handle memory, connections, and files properly

### When to Optimize
- After identifying actual bottlenecks through profiling
- When performance issues are measurable
- Optimize only after measurable bottlenecks are identified, not during initial development

## Code Organization

### Structural Principles
- **Group related functionality**: Keep related code together
- **Separate concerns**: Domain logic, data access, presentation
- **Consistent naming**: Follow project conventions
- **Module cohesion**: High cohesion within modules, low coupling between

### File Organization
- One primary responsibility per file
- Logical grouping of related functions/classes
- Clear folder structure reflecting architecture
- Avoid "god files" (files > 500 lines)

## Commenting Principles

### Default: code first
Names, types, and structure are the primary medium. A comment earns its place only by carrying information the code itself cannot express. When in doubt, improve the name instead of adding a comment.

### The test for every comment
A comment is justified only if it answers one of these:
- **Why**: reasoning, trade-off, or constraint behind a non-obvious decision
- **Limitation / edge case**: a boundary a reader cannot infer from the code
- **Public API contract**: behavior, inputs, outputs of an exported interface

One comment per decision. If a comment restates what the names and control flow already show, delete it and rename instead.

### Comment Scope
- Comment the why, limits, and public contracts (per the test above); let names and structure carry everything else, including the "how"
- Record historical context in version control commit messages, not in comments
- Delete commented-out code (retrieve from git history when needed)

### Comment Quality
- Write comments that remain accurate regardless of future code changes; avoid references to dates, versions, or temporary state
- Update comments when changing code
- Use proper grammar and formatting
- Write for future maintainers

## Refactoring Approach

### Safe Refactoring
- **Small steps**: Make one change at a time
- **Maintain working state**: Keep tests passing
- **Verify behavior**: Run tests after each change
- **Incremental improvement**: Don't aim for perfection immediately

### Refactoring Triggers
- Code duplication (DRY principle)
- Functions > 50 lines
- Complex conditional logic
- Unclear naming or structure

## Testing Considerations

### Testability
- Write testable code from the start
- Avoid hidden dependencies
- Keep side effects explicit
- Design for parameterized dependencies

### Test-Driven Development
- Write tests before implementation when appropriate
- Keep tests simple and focused
- Test behavior, not implementation
- Maintain test quality equal to production code

## Security Principles

### Secure Defaults
- Store credentials and secrets through environment variables or dedicated secret managers
- Use parameterized queries (prepared statements) for all database access
- Use established cryptographic libraries provided by the language or framework
- Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
- Encrypt sensitive data at rest and in transit using standard protocols

### Input and Output Boundaries
- Validate all external input at system entry points for expected format, type, and length
- Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
- Return only information necessary for the caller in error responses; log detailed diagnostics server-side

### Access Control
- Apply authentication to all entry points that handle user data or trigger state changes
- Verify authorization for each resource access, not only at the entry point
- Grant only the permissions required for the operation (files, database connections, API scopes)

### Knowledge Cutoff Supplement (2026-03)
- OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10)
- Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets
- OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice
- For detailed detection patterns, see `references/security-checks.md`

## Documentation

### Code Documentation
- Document public APIs and interfaces
- Include usage examples for complex functionality
- Maintain README files for modules
- Update documentation in the same commit that changes the corresponding behavior

### Architecture Documentation
- Document high-level design decisions
- Explain integration points
- Clarify data flows and boundaries
- Record trade-offs and alternatives considered

## Version Control Practices

### Commit Practices
- Make atomic, focused commits
- Write clear, descriptive commit messages
- Commit working code (passes tests)
- Commit only production-ready code; store secrets in environment variables or secret managers

### Code Review Readiness
- Self-review before requesting review
- Keep changes focused and reviewable
- Provide context in pull request descriptions
- Respond to feedback constructively

## Language-Specific Adaptations

While these principles are language-agnostic, adapt them to your specific programming language:

- **Static typing**: Use strong types when available
- **Dynamic typing**: Add runtime validation
- **OOP languages**: Apply SOLID principles
- **Functional languages**: Prefer pure functions and immutability
- **Concurrency**: Follow language-specific patterns for thread safety

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shinpr](https://github.com/shinpr)
- **Source:** [shinpr/claude-code-workflows](https://github.com/shinpr/claude-code-workflows)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-shinpr-claude-code-workflows-coding-principles
- Seller: https://agentstack.voostack.com/s/shinpr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.