| name | software-clean-code-standard |
| description | Defines clean-code standards and CC-* rules. Use when reviewing code, setting team standards, citing lint findings, or measuring erosion, complexity mass, and verbosity. |
| compatibility | Portable core. Works on Claude Code and Codex. |
| version | 1.2 |
| last_validated | 2026-08-21T00:00:00.000Z |
Clean Code Standard
This skill is the authoritative clean code standard for this repository's shared skills. It defines stable rule IDs (CC-*), how to apply them in reviews, and how to extend them safely via language overlays and explicit exceptions.
Modern Best Practices: Prefer small, reviewable changes and durable change context. Use BCP 14 normative language consistently (RFC 2119 + RFC 8174). Treat security-by-design and secure defaults as baseline (OWASP Top Ten 2025, NIST SSDF). Prefer GitHub rulesets over branch-protection-only governance. Build observable systems with OpenTelemetry. For current tool choices, consult data/sources.json and prefer official docs first.
Judgment over dogma: This standard's CC-* rules are durable (coupling/cohesion, naming, small interfaces, explicit errors). Numeric folklore — hard function-length caps, "comments are a smell," DRY applied absolutely — is not. Robert C. Martin's Clean Code (2nd ed., 2025) and John Ousterhout's A Philosophy of Software Design disagree in a published, public debate on function size and commenting (see references/code-quality-operational-playbook.md § 14); apply the rule ID's intent, not a book's specific numeric prescription, and know when not to refactor (§ 14.3 of the same reference).
Quick Reference
| Task | Tool/Framework | Command | When to Use |
|---|
| Cite a standard | CC-* rule ID | N/A | PR review comments, design discussions, postmortems |
| Categorize feedback | CC-NAM, CC-ERR, CC-SEC, etc. | N/A | Keep feedback consistent without "style wars" |
| Add stack nuance | Language overlay | N/A | When the base rule is too generic for a language/framework |
| Allow an exception | Waiver record | N/A | When a rule must be violated with explicit risk |
| Reuse shared checklists | assets/checklists/ | N/A | When you need product-agnostic review/release checklists |
| Reuse utility patterns | references/*-utilities.md | N/A | When extracting shared auth/logging/errors/resilience/testing utilities |
When to Use This Skill
- Defining or enforcing clean code rules across teams and languages.
- Reviewing code: cite
CC-* IDs and avoid restating standards in reviews.
- Building automation: map linters/CI gates to
CC-* IDs.
- Resolving recurring review debates: align on rule IDs, scope, and exceptions.
When NOT to Use This Skill
Workflow
- Decide whether the request is about a base rule, an overlay, or an exception.
- Route security, review-process, or refactoring mechanics to the adjacent skill if that is the real problem.
- Anchor the guidance in existing
CC-* rules before proposing new wording or automation.
- Apply the relevant standard, overlay, or waiver pattern with explicit scope and rationale.
- Cross-check against the navigation references before adding or revising durable standards.
Rule Application Checklist
When citing or enforcing CC-* rules in a review:
ASCII Flow
Clean-code request
-> Identify behavior that must stay unchanged
-> Find duplication, unclear boundaries, or unsafe complexity
-> Refactor in the smallest coherent slice
-> Preserve public contracts and naming consistency
-> Add or adjust tests for changed control flow
-> Run focused verification and report residual risk
Decision Tree: Base Rule vs Overlay vs Exception
Feedback needed: [What kind of guidance is this?]
├─ Universal, cross-language rule? → Add/modify `CC-*` in `references/clean-code-standard.md`
│
├─ Language/framework-specific nuance? → Add overlay entry referencing existing `CC-*`
│
└─ One-off constraint or temporary tradeoff?
├─ Timeboxed? → Add waiver with expiry + tracking issue
└─ Permanent? → Propose a new rule or revise scope/exception criteria
Optional: AI/Automation
- Map automation findings to
CC-* IDs (linters, SAST, dependency scanning) so humans can review impact, not tooling noise.
- Keep AI-assisted suggestions advisory; human reviewers approve/deny with rule citations (https://conventionalcomments.org/).
- Prefer GitHub rulesets, SARIF-capable scanners, and repository-native code scanning for durable enforcement/reporting.
Reviewing AI-Generated Code
AI-generated code requires the same CC-* standards plus additional vigilance for these patterns:
| Pattern | CC-* Mapping | Detection |
|---|
| Hallucinated imports | CC-DEP-* | npm info / pip index / type-check fails |
| Stale or deprecated APIs | CC-DEP-* | Compiler warnings, changelog checks |
| Missing error paths | CC-ERR-* | No catch/finally, no null guards, no timeout |
| Premature abstraction | CC-COMPLEXITY-* | Wrappers with single call site, unused generics |
| Confident wrong comments | CC-NAMING-* | Docstrings that don't match implementation |
| Security anti-patterns | CC-SEC-* | String concatenation in queries, hardcoded tokens |
For detailed hallucination detection steps, see references/code-quality-operational-playbook.md § 11.3.
Navigation
Resources
Templates
Utility Patterns
Related Skills
Freshness Protocol
IMPORTANT: When users ask recommendation questions about clean code standards, linters, formatters, static analysis, or code quality tools, you MUST verify current guidance with web search and official docs before answering. If web search is unavailable, say so and answer using data/sources.json, clearly flagging that the recommendation may be stale.
Trigger Conditions
- "What's the best linter for [language]?"
- "What should I use for [code quality/static analysis]?"
- "What's the latest in clean code practices?"
- "Current best practices for [code standards/formatting]?"
- "Is [ESLint/Prettier/Biome] still relevant?"
- "[Biome] vs [ESLint] vs [other]?"
- "Best static analysis tool for [language]?"
- "Should we switch from [legacy tool] to [new tool]?"
- "What should we use in CI for code scanning or code quality gates?"
Required Verification Workflow
- Check official docs first for the named tool(s): current docs, release notes/changelog, migration guidance, and supported workflows.
- Check the official standard/spec when relevant: RFCs, OWASP, NIST, OpenTelemetry, GitHub Docs.
- Use web search for cross-tool comparisons or current adoption trends only after confirming the primary-source facts.
- Prefer at most one neutral secondary comparison source when the user explicitly wants market positioning or tradeoff analysis.
What to Report
After verifying, provide:
- Current default choice: What you would adopt now for the user’s stack and why
- Current landscape: Which tools are current, maintained, and commonly paired together
- Migration risk: Flat config changes, rule-coverage gaps, formatter/linter consolidation, CI/reporting implications
- Deprecated/declining: Tools or approaches losing relevance for this use case
- Recommendation: Based on fresh official data, not static memory
Example Topics (verify with fresh search)
- JavaScript/TypeScript linters (ESLint, Biome, oxlint)
- Formatters (Prettier, dprint, Biome)
- Python quality (Ruff,
ty, mypy, pylint)
- Go linting (golangci-lint, staticcheck)
- Rust analysis (clippy, cargo-deny)
- Code quality metrics and reporting tools
- Code scanning and security automation (CodeQL, Semgrep, SARIF workflows)
- GitHub enforcement controls (rulesets, CODEOWNERS, protected branches)
Known Traps
- Treating “clean code” as style preference only and ignoring correctness, observability, security, and change safety.
- Enforcing blanket abstraction rules that increase indirection and reduce runtime clarity in the name of cleanliness.
- Mixing language-specific formatter and linter opinions into universal guidance without preserving the stable CC rule intent.
- Letting tool defaults silently redefine the team standard when the explicit repository rule IDs say otherwise.
- Auditing code solely from static style output and missing failure-mode, data-boundary, and operability risks.
Common Anti-Patterns
- Replacing concrete, understandable code with layered abstractions just to satisfy a cleanliness aesthetic.
- Treating short functions, DRY, or naming rules as absolute even when they harm cohesion, locality, or domain clarity.
- Using “clean code” to block pragmatic duplication that preserves boundaries or avoids premature frameworks.
- Turning rule IDs into checklist theater with no explanation of why the rule matters for maintainability or safety.
- Applying one language ecosystem’s conventions wholesale to another without adaptation for tooling, runtime, and team workflow.
Fact-Checking
- Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
- Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
- Prefer primary sources; report source links and dates for volatile information, and distinguish facts from inference.
- If web access is unavailable, state the limitation and mark guidance as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
