跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 coding-principles

Coding Principles

语言不可知性编码原则,用于可维持性,可读性和质量. 在执行特性时使用,重构代码,或审查代码质量.

73 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

可维持性、可读性和质量的语言不可知编码原则

何时用

执行特性、重构代码或审查代码质量

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Language-Agnostic Coding Principles、Core Philosophy、Code Quality、Continuous Improvement、Readability、Function Design。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/security-checks.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

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

Language-Agnostic Coding PrinciplesCore PhilosophyCode QualityContinuous ImprovementReadabilityFunction DesignParameter ManagementSingle ResponsibilityFunction OrganizationError HandlingError Management PrinciplesError Propagation

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
coding-principles
description
Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 1
  • references/security-checks.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「coding-principles」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-cc4756a6907bbe41-%E7%BC%96%E7%A0%81%E5%8E%9F%E5%88%99.html
请存为 .cursor/skills/coding-principles/SKILL.md 或 .claude/skills/coding-principles/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/shinpr/claude-code-workflows 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/shinpr/claude-code-workflows' --list

npx skills add 'https://github.com/shinpr/claude-code-workflows' --skill 'coding-principles'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

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

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

Single Responsibility

  • Each function should do one thing well
  • Extract a function when independently changing responsibilities or obscured control flow make the current unit harder to understand, verify, or reuse; retain a cohesive domain flow when extraction would create artificial coupling
  • Extract complex logic into separate, well-named functions
  • Functions should have a single level of abstraction

Function Organization

  • Pure functions when possible (no side effects)
  • Separate data transformation from side effects
  • Use early returns to reduce nesting
  • Use early returns or extraction when nesting obscures state transitions or decision ownership; retain nested structure when it maps the domain decision more clearly

Error Handling

Error Management Principles

  • Always handle errors: Log with context or propagate explicitly
  • Log appropriately: Include context for debugging
  • Protect sensitive data: Mask or exclude passwords, tokens, PII from logs
  • Fail fast: Detect and report errors as early as possible

Error Propagation

  • Use language-appropriate error handling mechanisms
  • Propagate errors to appropriate handling levels
  • Provide meaningful error messages
  • Include error context when re-throwing

Dependency Management

Loose Coupling via Parameterized Dependencies

  • Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)
  • Depend on abstractions, not concrete implementations
  • Minimize inter-module dependencies
  • Facilitate testing through mockable dependencies

Reference Representativeness

Verifying References Before Adoption

When adopting patterns, APIs, or dependencies from existing code:

  • IF a reference sample covers only nearby files → THEN confirm the pattern is representative by checking relevant repository usage before adopting
  • IF multiple approaches coexist in the repository → THEN identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient
  • IF adopting an external dependency (library, plugin, SDK) → THEN verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it
  • IF following an existing pattern → THEN state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)

Principle

Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model.

Performance Considerations

Optimization Approach

  • Measure first: Profile before optimizing
  • Focus on algorithms: Algorithmic complexity > 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
  • Split a file when it contains independently changing responsibilities or creates material navigation, coupling, or verification cost; retain a cohesive file when splitting would add avoidable coupling or navigation cost

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

  • Base comments on stable rationale, limits, and contracts rather than 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: Make the smallest sufficient improvement in each increment

Refactoring Triggers

  • Code duplication (DRY principle)
  • Functions that contain independently changing responsibilities or obscured control flow
  • Complex conditional logic
  • Unclear naming or structure

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)
  • For changes involving identity or protected resources, prioritize authentication and per-resource authorization review

For concrete detection patterns used by security review, see references/security-checks.md.

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…