القائمة
提供组件级设计原则，包括类/模块设计、接口设计、数据模型、并发模型、错误处理。在系统设计阶段讨论组件详细设计时使用，或在 code review 中评估组件质量时使用。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/davidYichengWei/agentic-engineering-framework --skill bp-component-designيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
代码文件修改的统一入口。当用户请求任何代码变更（新功能、优化、Bug 修复、重构）时必须首先调用此 skill。仅适用于代码文件（如 .cc/.cpp/.h/.go/.py 等），修改 .md 等非代码文件时不需要调用。它会评估复杂度、检查 spec.md、生成 tasks.md、并逐个任务执行。
测试生成。基于 spec.md 或被测代码，生成单元测试、集成测试、性能测试。当用户请求生成测试、TDD 模式、或 workflow-code-generation 完成后触发。
将纠错经验沉淀为持久化的 Rules/Skills 更新，构建反馈闭环。当被用户纠正且错误具有模式性时自动触发，或通过 /reflect 命令手动触发回顾。
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | bp-component-design |
| description | 提供组件级设计原则，包括类/模块设计、接口设计、数据模型、并发模型、错误处理。在系统设计阶段讨论组件详细设计时使用，或在 code review 中评估组件质量时使用。 |
使用场景：
workflow-system-designskill 在讨论 spec.md 4.2 组件设计 时加载本 skill。
组件设计的本质：把架构方案转化为可实现的代码结构，定义清晰的职责边界和交互契约。
| 原则 | 含义 | 检查点 |
|---|---|---|
| Single Responsibility | 类只做一件事 | 这个类能用一句话描述吗？ |
| Open/Closed | 对扩展开放，对修改关闭 | 新增功能是否需要改现有代码？ |
| Liskov Substitution | 子类可替换父类 | 子类是否违反父类契约？ |
| Interface Segregation | 接口精简专一 | 调用方是否被迫依赖不需要的方法？ |
| Dependency Inversion | 依赖抽象而非具体 | 高层模块是否直接依赖低层实现？ |
| 原则 | 说明 |
|---|---|
| 组合优于继承 | 继承紧耦合，组合松耦合易替换 |
| 面向接口编程 | 依赖抽象接口，而非具体实现 |
| 最小知识原则 | 避免链式调用暴露内部结构 |
| 类型 | 模式 | 适用场景 |
|---|---|---|
| 创建型 | Factory | 封装对象创建逻辑 |
| 创建型 | Builder | 分步构建复杂对象 |
| 结构型 | Adapter | 接口转换 |
| 结构型 | Decorator | 动态添加职责 |
| 行为型 | Strategy | 可替换算法 |
| 行为型 | Template Method | 定义算法骨架，子类实现细节 |
| 行为型 | Iterator | 数据流处理、管道模式 |
接口设计关注对外暴露的 public API，内部接口在 4.2.1 中定义。
| 原则 | 说明 |
|---|---|
| 最小化 | 只暴露必要的接口，隐藏实现细节 |
| 一致性 | 命名、参数顺序、错误处理风格统一 |
| 向后兼容 | 接口变更不破坏现有调用方 |
| 自描述 | 接口签名本身能表达意图 |
// 示例：接口定义应包含
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;
};
| 变更类型 | 兼容性 | 处理方式 |
|---|---|---|
| 新增方法 | 向后兼容 | 直接添加 |
| 新增可选参数 | 向后兼容 | 提供默认值 |
| 删除方法 | 不兼容 | 先废弃，下个大版本删除 |
| 修改参数类型 | 不兼容 | 新增方法，废弃旧方法 |
何时需要：涉及数据存储、Schema 变更、新增数据结构时。
| 要素 | 需要明确 |
|---|---|
| Schema | 字段定义、类型、约束 |
| 索引 | 查询模式决定索引设计 |
| 编码格式 | 序列化方式（protobuf/flatbuffers/自定义） |
| 存储位置 | 存哪里？生命周期？ |
| 策略 | 说明 |
|---|---|
| 向前兼容 | 新代码能读旧数据 |
| 向后兼容 | 旧代码能读新数据（需谨慎设计） |
| 迁移计划 | 如何从旧 Schema 迁移到新 Schema？ |
何时需要：涉及多线程、异步操作、共享状态时。
| 要素 | 需要明确 |
|---|---|
| 线程模型 | 哪些线程？职责是什么？ |
| 共享状态 | 哪些数据被多线程访问？ |
| 同步机制 | 用什么锁？锁的粒度？ |
| 异步边界 | 哪里是同步/异步的边界？ |
| 模式 | 适用场景 |
|---|---|
| 单线程 + 事件循环 | I/O 密集、低延迟 |
| 线程池 + 任务队列 | CPU 密集、可并行 |
| Actor 模型 | 状态隔离、消息传递 |
| 读写锁 | 读多写少 |
何时需要：涉及外部依赖、I/O 操作、可能失败的场景时。
| 要素 | 需要明确 |
|---|---|
| 失败模式 | 可能发生哪些错误？ |
| 错误表示 | 错误码 / 异常 / Status 对象？ |
| 重试策略 | 哪些错误可重试？退避策略？ |
| 恢复机制 | 失败后如何恢复到一致状态？ |
| 类型 | 示例 | 处理方式 |
|---|---|---|
| 可重试 | 网络超时、临时不可用 | 指数退避重试 |
| 不可重试 | 参数错误、权限不足 | 直接返回错误 |
| 致命错误 | 数据损坏、不变量被破坏 | 记录日志 + panic/abort |
// 指数退避 + 抖动
int delay_ms = min(base_delay * (1 << retry_count), max_delay);
delay_ms += random(0, delay_ms * 0.1); // 10% jitter
| 反模式 | 问题 | 改进 |
|---|---|---|
| God Class | 类承担过多职责 | 拆分为多个小类 |
| Feature Envy | 方法大量访问其他类数据 | 移动到数据所在类 |
| 过度设计 | 不需要的抽象层 | 简单优先，按需抽象 |
| 忽略错误 | 吞掉错误不处理 | 明确处理或向上传播 |
| 锁粒度过粗 | 整个操作加大锁 | 缩小临界区 |
| 场景 | 加载 Skill |
|---|---|
| 涉及分布式场景（网络、一致性、故障） | bp-distributed-systems |
| 涉及性能优化 | bp-performance-optimization |