Back to Details

software-clean-code-standard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clean Code Standard — Quick Reference

整洁代码标准——快速参考

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 (January 2026): Prefer small, reviewable changes and durable change context (https://google.github.io/eng-practices/review/developer/small-cls.html, https://google.github.io/eng-practices/review/developer/cl-descriptions.html). Use normative language consistently (RFC 2119: https://www.rfc-editor.org/rfc/rfc2119). Treat security-by-design and secure defaults as baseline (OWASP Top 10: https://owasp.org/www-project-top-ten/, NIST SSDF SP 800-218: https://csrc.nist.gov/pubs/sp/800/218/final). Build observable systems (OpenTelemetry: https://opentelemetry.io/docs/). For current tool choices, consult 
data/sources.json
.
本Skill是本仓库共享技能的权威整洁代码标准。它定义了稳定的规则ID（
CC-*
）、如何在评审中应用这些规则，以及如何通过语言覆盖层和明确的例外情况安全地扩展规则。
现代最佳实践（2026年1月）：优先选择小型、易于评审的变更，并保留持久的变更上下文（https://google.github.io/eng-practices/review/developer/small-cls.html, https://google.github.io/eng-practices/review/developer/cl-descriptions.html）。统一使用规范性语言（RFC 2119: https://www.rfc-editor.org/rfc/rfc2119）。将安全设计和安全默认值作为基线（OWASP Top 10: https://owasp.org/www-project-top-ten/, NIST SSDF SP 800-218: https://csrc.nist.gov/pubs/sp/800/218/final）。构建可观测系统（OpenTelemetry: https://opentelemetry.io/docs/）。如需了解当前工具选择，请查阅`data/sources.json`。

Quick Reference

快速参考

TaskTool/FrameworkCommandWhen to Use
Cite a standard
CC-*
rule ID		N/APR review comments, design discussions, postmortems
Categorize feedback
CC-NAM
, 
CC-ERR
, 
CC-SEC
, etc.		N/AKeep feedback consistent without "style wars"
Add stack nuanceLanguage overlayN/AWhen the base rule is too generic for a language/framework
Allow an exceptionWaiver recordN/AWhen a rule must be violated with explicit risk
Reuse shared checklists
assets/checklists/
N/AWhen you need product-agnostic review/release checklists
Reuse utility patterns
utilities/
N/AWhen extracting shared auth/logging/errors/resilience/testing utilities
任务工具/框架命令适用场景
引用标准
CC-*
规则ID		N/APR评审评论、设计讨论、事后复盘
分类反馈
CC-NAM
、
CC-ERR
、
CC-SEC
等		N/A保持反馈一致性，避免“风格之争”
添加技术栈细节语言覆盖层N/A当基础规则对于某一语言/框架过于通用时
允许例外情况豁免记录N/A当必须违反规则且需明确风险时
复用共享检查清单
assets/checklists/
N/A需要与产品无关的评审/发布检查清单时
复用工具模式
utilities/
N/A提取共享的认证/日志/错误处理/韧性/测试工具时

When to Use This Skill

何时使用本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.
  • 在跨团队、跨语言场景下定义或执行整洁代码规则。
  • 代码评审：引用
    CC-*
    ID，避免在评审中重复陈述标准。
  • 构建自动化：将代码检查工具/CI门禁映射到
    CC-*
    ID。
  • 解决反复出现的评审争议：对齐规则ID、范围和例外情况。

When NOT to Use This Skill

何时不使用本Skill

  • Deep security audits: Use software-security-appsec for OWASP/SAST deep dives beyond 
    CC-SEC-*
    baseline.
  • Review workflow mechanics: Use software-code-review for PR workflow, reviewer assignment, and feedback patterns.
  • Refactoring execution: Use qa-refactoring for step-by-step refactoring patterns and quality gates.
  • Architecture decisions: Use software-architecture-design for system-level tradeoffs beyond code-level rules.
  • 深度安全审计：对于超出
    CC-SEC-*
    基线的OWASP/SAST深度分析，请使用software-security-appsec。
  • 评审工作流机制：关于PR工作流、评审人员分配和反馈模式，请使用software-code-review。
  • 重构执行：关于分步重构模式和质量门禁，请使用qa-refactoring。
  • 架构决策：关于系统层面的权衡（超出代码级规则），请使用software-architecture-design。

Decision Tree: Base Rule vs Overlay vs Exception

决策树：基础规则 vs 覆盖层 vs 例外情况

text
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
text
需要提供反馈：[这是哪类指导？]
    ├─ 通用跨语言规则？ → 在`references/clean-code-standard.md`中添加/修改`CC-*`规则
    │
    ├─ 语言/框架特定细节？ → 添加引用现有`CC-*`规则的覆盖层条目
    │
    └─ 一次性约束或临时权衡？
        ├─ 有时间限制？ → 添加带到期时间和跟踪议题的豁免记录
        └─ 永久有效？ → 提议新规则或修订规则范围/例外条件

Navigation

导航

Resources
  • references/clean-code-standard.md
  • references/code-quality-operational-playbook.md — Legacy operational playbook (RULE-01–RULE-13)
  • references/clean-code-operational-checklist.md
  • references/clean-coder-operational-checklist.md
  • references/code-complete-operational-checklist.md
  • references/pragmatic-programmer-operational-checklist.md
  • references/practice-of-programming-operational-checklist.md
  • references/working-effectively-with-legacy-code-operational-checklist.md
  • references/art-of-clean-code-operational-checklist.md
  • references/refactoring-operational-checklist.md
  • references/design-patterns-operational-checklist.md
  • data/sources.json — Durable external references for review, security-by-design, and observability
  • CONVENTIONS.md — Skill structure and validation conventions
  • SKILL-TEMPLATE.md — Copy-paste starter for new skills
  • sources-schema.json — JSON schema for 
    data/sources.json
  • skill-dependencies.json — Related-skills dependency graph
Templates
  • assets/checklists/backend-api-review-checklist.md
  • assets/checklists/secure-code-review-checklist.md
  • assets/checklists/frontend-performance-a11y-checklist.md
  • assets/checklists/mobile-release-checklist.md
  • assets/checklists/ux-design-review-checklist.md
  • assets/checklists/ux-research-plan-template.md
Utilities
  • utilities/README.md
  • utilities/auth-utilities.md
  • utilities/error-handling.md
  • utilities/config-validation.md
  • utilities/resilience-utilities.md
  • utilities/logging-utilities.md
  • utilities/observability-utilities.md
  • utilities/testing-utilities.md
  • utilities/llm-utilities.md
Related Skills
  • ../software-code-review/SKILL.md — Review workflow and judgment; cite 
    CC-*
    IDs
  • ../software-security-appsec/SKILL.md — Security deep dives beyond baseline 
    CC-SEC-*
  • ../qa-refactoring/SKILL.md — Refactoring execution patterns and quality gates
  • ../software-architecture-design/SKILL.md — System-level tradeoffs and boundaries
资源
  • references/clean-code-standard.md
  • references/code-quality-operational-playbook.md — 旧版操作手册（RULE-01–RULE-13）
  • references/clean-code-operational-checklist.md
  • references/clean-coder-operational-checklist.md
  • references/code-complete-operational-checklist.md
  • references/pragmatic-programmer-operational-checklist.md
  • references/practice-of-programming-operational-checklist.md
  • references/working-effectively-with-legacy-code-operational-checklist.md
  • references/art-of-clean-code-operational-checklist.md
  • references/refactoring-operational-checklist.md
  • references/design-patterns-operational-checklist.md
  • data/sources.json — 用于评审、安全设计和可观测性的持久外部参考
  • CONVENTIONS.md — Skill结构和验证规范
  • SKILL-TEMPLATE.md — 用于创建新Skill的复制粘贴模板
  • sources-schema.json — 
    data/sources.json
    的JSON schema
  • skill-dependencies.json — 相关Skill的依赖关系图
模板
  • assets/checklists/backend-api-review-checklist.md
  • assets/checklists/secure-code-review-checklist.md
  • assets/checklists/frontend-performance-a11y-checklist.md
  • assets/checklists/mobile-release-checklist.md
  • assets/checklists/ux-design-review-checklist.md
  • assets/checklists/ux-research-plan-template.md
工具
  • utilities/README.md
  • utilities/auth-utilities.md
  • utilities/error-handling.md
  • utilities/config-validation.md
  • utilities/resilience-utilities.md
  • utilities/logging-utilities.md
  • utilities/observability-utilities.md
  • utilities/testing-utilities.md
  • utilities/llm-utilities.md
相关Skill
  • ../software-code-review/SKILL.md — 评审工作流和判断；引用
    CC-*
    ID
  • ../software-security-appsec/SKILL.md — 超出基线
    CC-SEC-*
    的深度安全分析
  • ../qa-refactoring/SKILL.md — 重构执行模式和质量门禁
  • ../software-architecture-design/SKILL.md — 系统层面的权衡和边界定义

Optional: AI/Automation

可选：AI/自动化

  • 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/).
  • 将自动化检查结果映射到
    CC-*
    ID（代码检查工具、SAST、依赖扫描），以便人工评审关注影响而非工具噪声。
  • AI辅助建议仅作为参考；人工评审员需通过规则引用批准/拒绝建议（https://conventionalcomments.org/）。

Trend Awareness Protocol

趋势感知协议

IMPORTANT: When users ask recommendation questions about clean code standards, linters, or code quality tools, you MUST use a web search capability (if available) to check current trends before answering. If web search is unavailable, say so and answer using 
data/sources.json
, clearly flagging that the recommendation may be stale.
重要提示：当用户询问关于整洁代码标准、代码检查工具或代码质量工具的推荐问题时，若具备网页搜索能力，必须先搜索当前趋势再作答。若无法进行网页搜索，请明确说明，并使用
data/sources.json
中的内容作答，同时清晰标注推荐内容可能已过时。

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 in 2026?"
  • "[Biome] vs [ESLint] vs [other]?"
  • "Best static analysis tool for [language]?"
  • “[语言]的最佳代码检查工具是什么？”
  • “[代码质量/静态分析]应该用什么工具？”
  • “整洁代码实践的最新趋势是什么？”
  • “[代码标准/格式化]的当前最佳实践是什么？”
  • “[ESLint/Prettier/Biome]在2026年还适用吗？”
  • “[Biome] vs [ESLint] vs [其他工具]？”
  • “[语言]的最佳静态分析工具是什么？”

Required Searches

必做搜索

  1. Search: 
    "clean code best practices 2026"
  2. Search: 
    "[specific linter] vs alternatives 2026"
  3. Search: 
    "code quality tools trends 2026"
  4. Search: 
    "[language] linter comparison 2026"
  1. 搜索：
    "clean code best practices 2026"
  2. 搜索：
    "[特定代码检查工具] vs alternatives 2026"
  3. 搜索：
    "code quality tools trends 2026"
  4. 搜索：
    "[language] linter comparison 2026"

What to Report

需报告内容

After searching, provide:
  • Current landscape: What linters/formatters are popular NOW
  • Emerging trends: New tools, standards, or patterns gaining traction
  • Deprecated/declining: Tools/approaches losing relevance or support
  • Recommendation: Based on fresh data, not just static knowledge
搜索后需提供：
  • 当前格局：现在流行的代码检查工具/格式化工具
  • 新兴趋势：正在获得关注的新工具、标准或模式
  • 已弃用/衰退：正在失去相关性或支持的工具/方法
  • 推荐建议：基于最新数据，而非仅静态知识

Example Topics (verify with fresh search)

示例主题（需通过最新搜索验证）

  • JavaScript/TypeScript linters (ESLint, Biome, oxlint)
  • Formatters (Prettier, dprint, Biome)
  • Python quality (Ruff, mypy, pylint)
  • Go linting (golangci-lint, staticcheck)
  • Rust analysis (clippy, cargo-deny)
  • Code quality metrics and reporting tools
  • AI-assisted code review tools
  • JavaScript/TypeScript代码检查工具（ESLint、Biome、oxlint）
  • 格式化工具（Prettier、dprint、Biome）
  • Python质量工具（Ruff、mypy、pylint）
  • Go代码检查工具（golangci-lint、staticcheck）
  • Rust分析工具（clippy、cargo-deny）
  • 代码质量指标和报告工具
  • AI辅助代码评审工具 ",