Agent skill

Component Design Principles

by davidYichengWei in davidYichengWei/agentic-engineering-framework

Chinese-language checklists for component-level design: class and module structure, public interfaces, data models, concurrency and error handling.

MITAuto-check passedDevelopment

SKILL.md written in Chinese; this summary is our English description.

Install Component Design Principles

skills CLI
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/davidYichengWei/agentic-engineering-framework.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/bp-component-design .claude/skills/bp-component-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
bp-component-design
GitHub stars
158
Token cost
~1k tokens
SKILL.md length
262 words
Files
1
Skills in repo
14
Repo updated
First seen
Licence
MIT

At a glance

Chinese-language checklists for component-level design: class and module structure, public interfaces, data models, concurrency and error handling.

  • Discussing component-level detailed design during system design
  • SKILL.md covers 第一性原理, 4.2.1 核心类/模块设计, 4.2.2 接口设计 and 4.2.3 数据模型, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Reviewing class, interface or data model quality in a code review

What it does

A reference loaded by a system-design workflow when it reaches the component design section of a spec, and also useful when judging component quality in a code review. It opens with the idea that component design turns an architecture into implementable code structure with clear responsibility boundaries. The class and module part lists the SOLID principles with a check question for each, favors composition over inheritance and programming to interfaces, tabulates common patterns (Factory, Builder, Adapter, Decorator, Strategy, Template Method, Iterator) and ends with a checklist.

Interface design asks for minimal, consistent, backward-compatible and self-describing public APIs, with a C++ example and a table of which changes break compatibility (adding methods is safe, deleting a method or changing a parameter type is not). The data model section covers schema, indexes, encoding and storage location, plus forward and backward compatibility and migration plans. The concurrency section covers thread model, shared state, locking and sync-async boundaries, with patterns such as event loops, thread pools, actors and read-write locks.

When your agent uses it

  • Discussing component-level detailed design during system design
  • Reviewing class, interface or data model quality in a code review
  • Checking a design's thread model and how shared state is protected
  • Planning backward-compatible API or schema changes

Example prompts

  • “Review the design of our StorageEngine class against SOLID and tell me where responsibilities blur.”
  • “Check this public interface for minimality, error codes and thread safety notes.”
  • “We are adding a column to the events table. What schema evolution and migration points should the design cover?”
  • “Walk through the concurrency model for the new worker pool: threads, shared state and locks.”

What it can do on your machine

Read from SKILL.md and the folder at commit 1f7ac0f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are cpp).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Component Design Principles loads about 1k tokens when it runs. Until then it costs about 26 tokens; SKILL.md has 262 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~26
When it runs · the whole SKILL.md, loaded when a task matches
~1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from davidYichengWei/agentic-engineering-framework at commit 1f7ac0f, republished under its MIT licence (© davidYichengWei). 262 words, ~1,023 tokens.

Download SKILL.mdSave it as .claude/skills/bp-component-design/SKILL.md (or your agent's skills folder).
name
bp-component-design
description
提供组件级设计原则,包括类/模块设计、接口设计、数据模型、并发模型、错误处理。在系统设计阶段讨论组件详细设计时使用,或在 code review 中评估组件质量时使用。

组件设计

使用场景:workflow-system-design skill 在讨论 spec.md 4.2 组件设计 时加载本 skill。

第一性原理

组件设计的本质:把架构方案转化为可实现的代码结构,定义清晰的职责边界和交互契约。


4.2.1 核心类/模块设计

SOLID 原则
原则含义检查点
Single Responsibility类只做一件事这个类能用一句话描述吗?
Open/Closed对扩展开放,对修改关闭新增功能是否需要改现有代码?
Liskov Substitution子类可替换父类子类是否违反父类契约?
Interface Segregation接口精简专一调用方是否被迫依赖不需要的方法?
Dependency Inversion依赖抽象而非具体高层模块是否直接依赖低层实现?
设计原则
原则说明
组合优于继承继承紧耦合,组合松耦合易替换
面向接口编程依赖抽象接口,而非具体实现
最小知识原则避免链式调用暴露内部结构
常用设计模式
类型模式适用场景
创建型Factory封装对象创建逻辑
创建型Builder分步构建复杂对象
结构型Adapter接口转换
结构型Decorator动态添加职责
行为型Strategy可替换算法
行为型Template Method定义算法骨架,子类实现细节
行为型Iterator数据流处理、管道模式
Checklist
  • 类职责是否单一清晰?
  • 继承层次是否合理(不超过 2-3 层)?
  • 依赖是否指向抽象而非具体实现?
  • 模块边界是否明确?

4.2.2 接口设计

接口设计关注对外暴露的 public API,内部接口在 4.2.1 中定义。

设计原则
原则说明
最小化只暴露必要的接口,隐藏实现细节
一致性命名、参数顺序、错误处理风格统一
向后兼容接口变更不破坏现有调用方
自描述接口签名本身能表达意图
接口定义要素
cpp
// 示例:接口定义应包含
class StorageEngine {
public:
    // 1. 方法签名:清晰的命名和参数
    // 2. 参数约束:哪些可为空?取值范围?
    // 3. 返回值:成功/失败如何表示?
    // 4. 错误码:可能返回哪些错误?
    // 5. 线程安全:是否可并发调用?
    
    /**
     * @brief 写入 KV 对
     * @param key 键,不能为空
     * @param value 值
     * @return Status::OK 成功
     *         Status::KeyTooLong key 超过 64KB
     *         Status::IOError 写入失败
     * @thread_safety 线程安全
     */
    virtual Status Put(const Slice& key, const Slice& value) = 0;
};
版本兼容策略
变更类型兼容性处理方式
新增方法向后兼容直接添加
新增可选参数向后兼容提供默认值
删除方法不兼容先废弃,下个大版本删除
修改参数类型不兼容新增方法,废弃旧方法
Checklist
  • 接口是否最小化(不暴露不必要的方法)?
  • 参数和返回值是否清晰定义?
  • 错误码是否完整列出?
  • 线程安全性是否说明?
  • 是否考虑了向后兼容?

4.2.3 数据模型

何时需要:涉及数据存储、Schema 变更、新增数据结构时。

设计要素
要素需要明确
Schema字段定义、类型、约束
索引查询模式决定索引设计
编码格式序列化方式(protobuf/flatbuffers/自定义)
存储位置存哪里?生命周期?
Schema 演进
策略说明
向前兼容新代码能读旧数据
向后兼容旧代码能读新数据(需谨慎设计)
迁移计划如何从旧 Schema 迁移到新 Schema?
Checklist
  • Schema 字段是否完整定义?
  • 索引是否满足查询需求?
  • 是否考虑了 Schema 演进?
  • 迁移/回滚方案是否明确?

4.2.4 并发模型

何时需要:涉及多线程、异步操作、共享状态时。

设计要素
要素需要明确
线程模型哪些线程?职责是什么?
共享状态哪些数据被多线程访问?
同步机制用什么锁?锁的粒度?
异步边界哪里是同步/异步的边界?
常见模式
模式适用场景
单线程 + 事件循环I/O 密集、低延迟
线程池 + 任务队列CPU 密集、可并行
Actor 模型状态隔离、消息传递
读写锁读多写少
Checklist
  • 线程模型是否清晰?
  • 共享状态是否明确,保护机制是否合理?
  • 是否有死锁风险?
  • 锁粒度是否合适(不过粗也不过细)?

4.2.5 错误处理

何时需要:涉及外部依赖、I/O 操作、可能失败的场景时。

设计要素
要素需要明确
失败模式可能发生哪些错误?
错误表示错误码 / 异常 / Status 对象?
重试策略哪些错误可重试?退避策略?
恢复机制失败后如何恢复到一致状态?
错误分类
类型示例处理方式
可重试网络超时、临时不可用指数退避重试
不可重试参数错误、权限不足直接返回错误
致命错误数据损坏、不变量被破坏记录日志 + panic/abort
重试策略
cpp
// 指数退避 + 抖动
int delay_ms = min(base_delay * (1 << retry_count), max_delay);
delay_ms += random(0, delay_ms * 0.1);  // 10% jitter
Checklist
  • 所有可能的失败模式是否列出?
  • 错误表示方式是否统一?
  • 可重试 vs 不可重试是否区分?
  • 失败后的清理/恢复逻辑是否考虑?

反模式

反模式问题改进
God Class类承担过多职责拆分为多个小类
Feature Envy方法大量访问其他类数据移动到数据所在类
过度设计不需要的抽象层简单优先,按需抽象
忽略错误吞掉错误不处理明确处理或向上传播
锁粒度过粗整个操作加大锁缩小临界区

与其他 Skill 协同

场景加载 Skill
涉及分布式场景(网络、一致性、故障)bp-distributed-systems
涉及性能优化bp-performance-optimization

© davidYichengWei, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/bp-component-design of davidYichengWei/agentic-engineering-framework.

Open the folder on GitHubat commit 1f7ac0f

Compare with similar skills

Component Design Principles next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Component Design Principles compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Component Design Principles this skilldavidYichengWei/agentic-engineering-framework158—~1kAutomated safety check: PassMIT
Brooks Audithyhmrright/brooks-lint1.5k1 repos~537Automated safety check: PassMIT
Pattern Conformance AuditTotoro-jam/battle-tested-patterns345—~1.6kAutomated safety check: PassMIT
Backend Code Reviewlanggenius/dify158k—~676Automated safety check: PassCustom licence
Code Review Skillawesome-skills/code-review-skill2.1k—~2.8kAutomated safety check: NotesMIT
Architecture PatternsKartikLabhshetwar/better-shot2.4k2 repos~1.4kAutomated safety check: PassCustom licence

Similar skills

  • Brooks Audit

    hyhmrright/brooks-lint

    Architecture audit that maps module dependencies, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic engineering books.

    1.5k GitHub starsUsed in 1 repo~537 tokens
    DevelopmentAuto-check passed
  • Pattern Conformance Audit

    Totoro-jam/battle-tested-patterns

    Audits a codebase's existing patterns, such as rate limiters, circuit breakers and caches, against canonical invariants and flags mislabeled or divergent ones.

    345 GitHub stars~1.6k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Backend Code Review

    langgenius/dify

    Reviews backend code under api/ for concrete, reproducible defects, routes to rule packs for architecture, schema, repositories and SQLAlchemy, and ranks findings from P0 to P3.

    158k GitHub stars~676 tokensUpdated today
    DevelopmentAuto-check passed
  • Code Review Skill

    awesome-skills/code-review-skill

    Provides comprehensive code review guidance for React 19, Vue 3, Angular 17+, Svelte 5, Rust, TypeScript, Java, Java 8, PHP, Ruby, Rails, Python, Django, FastAPI, Go, C/.NET, Kotlin, Swift, Dart…

    2.1k GitHub stars~2.8k tokensUpdated 1 mo ago
    DevelopmentAuto-check: notes
  • Architecture Patterns

    KartikLabhshetwar/better-shot

    Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.

    2.4k GitHub starsUsed in 2 repos~1.4k tokens
    DevelopmentAuto-check passed
  • Reviews a pull request against the Pascal editor's architectural rules: package boundaries, registry-driven node composition, hook hygiene and selector performance.

    25k GitHub stars~7.5k tokensUpdated today
    DevelopmentAuto-check passed

More from davidYichengWei/agentic-engineering-framework

All 14 skills in this repo
  • Architecture Design Principles

    davidYichengWei/agentic-engineering-framework

    Gives architecture design principles for system design discussions and code review: module boundaries, dependency direction, data ownership and interface rules, plus a checklist.

    158 GitHub stars~545 tokensUpdated 6 mo ago
    Auto-check passed
  • General Coding Best Practices

    davidYichengWei/agentic-engineering-framework

    A checklist of language-neutral rules for writing and reviewing code: naming, function design, control flow, resource safety, comments and logging.

    158 GitHub stars~631 tokensUpdated 6 mo ago
    Auto-check passed
  • Skill Authoring Guide (Chinese)

    davidYichengWei/agentic-engineering-framework

    Chinese-language guide to writing and improving SKILL.md files: frontmatter rules, concise writing, progressive disclosure, common patterns and a pre-release checklist.

    158 GitHub stars~788 tokensUpdated 6 mo ago
    Auto-check passed
  • Self-Refinement from Corrections

    davidYichengWei/agentic-engineering-framework

    Turns mistakes you correct into proposed updates to persistent Rules and Skills so the same error does not recur in later sessions, triggered automatically or with /reflect.

    158 GitHub stars~575 tokensUpdated 6 mo ago
    Auto-check passed
  • Root-Cause Troubleshooting

    davidYichengWei/agentic-engineering-framework

    Diagnoses compile errors, runtime exceptions, failing tests, pipeline failures and production alerts from code and logs, giving a root cause before any fix.

    158 GitHub stars~646 tokensUpdated 6 mo ago
    Auto-check passed
  • Workflow Code Generation

    davidYichengWei/agentic-engineering-framework

    代码文件修改的统一入口。当用户请求任何代码变更(新功能、优化、Bug 修复、重构)时必须首先调用此 skill。仅适用于代码文件(如 .cc/.cpp/.h/.go/.py 等),修改 .md 等非代码文件时不需要调用。它会评估复杂度、检查 spec.md、生成 tasks.md、并逐个任务执行。

    158 GitHub stars~733 tokensUpdated 6 mo ago
    Auto-check passed

Categories

Questions about Component Design Principles

What does Component Design Principles do?

Chinese-language checklists for component-level design: class and module structure, public interfaces, data models, concurrency and error handling. A reference loaded by a system-design workflow when it reaches the component design section of a spec, and also useful when judging component quality in a code review. It opens with the idea that component design turns an architecture into implementable code structure with clear responsibility boundaries.

When should I use Component Design Principles?

Component Design Principles fits situations like: discussing component-level detailed design during system design; reviewing class, interface or data model quality in a code review; checking a design's thread model and how shared state is protected; planning backward-compatible API or schema changes.

How do I install Component Design Principles in Claude Code?

Run `npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a claude-code`. Or copy the skill folder (skills/bp-component-design in davidYichengWei/agentic-engineering-framework) into .claude/skills/bp-component-design in your project. Claude Code loads it when a task matches its description.

How do I install Component Design Principles in Codex?

Run `npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a codex`. Or copy the skill folder (skills/bp-component-design in davidYichengWei/agentic-engineering-framework) into .agents/skills/bp-component-design in your project. Codex loads it when a task matches its description.

Can I use Component Design Principles in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bp-component-design, .gemini/skills/bp-component-design, .github/skills/bp-component-design and .opencode/skills/bp-component-design in your project.

What does Component Design Principles need to run?

SKILL.md names no scripts, command-line tools or credentials: Component Design Principles is instructions for the agent only.

Does Component Design Principles access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Component Design Principles safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Component Design Principles use?

Component Design Principles is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Component Design Principles use?

About 1k tokens (SKILL.md is roughly 4.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Component Design Principles?

Skills that share tags, products or a category with Component Design Principles: Brooks Audit (hyhmrright/brooks-lint, 1.5k stars), Pattern Conformance Audit (Totoro-jam/battle-tested-patterns, 345 stars), Backend Code Review (langgenius/dify, 158k stars) and Code Review Skill (awesome-skills/code-review-skill, 2.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Component Design Principles?

davidYichengWei (a GitHub user) maintains it in davidYichengWei/agentic-engineering-framework, which has 158 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on March 25, 2026.

Source: davidYichengWei/agentic-engineering-framework on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.