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.
Agent skill
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.
SKILL.md written in Chinese; this summary is our English description.
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-design --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ 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-srcUse ~/.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/
Install the "bp-component-design" agent skill from https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-design into .claude/skills/bp-component-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bp-component-design", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-designType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-design --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/davidYichengWei/agentic-engineering-framework.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/bp-component-design .agents/skills/bp-component-design && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "bp-component-design" agent skill from https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-design into .agents/skills/bp-component-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bp-component-design", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-design --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/davidYichengWei/agentic-engineering-framework.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/bp-component-design .cursor/skills/bp-component-design && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "bp-component-design" agent skill from https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-design into .cursor/skills/bp-component-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bp-component-design", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/davidYichengWei/agentic-engineering-framework.git --path skills/bp-component-design--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-design --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/davidYichengWei/agentic-engineering-framework.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/bp-component-design .gemini/skills/bp-component-design && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "bp-component-design" agent skill from https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-design into .gemini/skills/bp-component-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bp-component-design", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-designInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/davidYichengWei/agentic-engineering-framework.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/bp-component-design .github/skills/bp-component-design && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "bp-component-design" agent skill from https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-design into .github/skills/bp-component-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bp-component-design", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add davidYichengWei/agentic-engineering-framework --skill bp-component-design -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install davidYichengWei/agentic-engineering-framework bp-component-design --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/davidYichengWei/agentic-engineering-framework.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/bp-component-design .opencode/skills/bp-component-design && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "bp-component-design" agent skill from https://github.com/davidYichengWei/agentic-engineering-framework/tree/main/skills/bp-component-design into .opencode/skills/bp-component-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bp-component-design", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
bp-component-designChinese-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. 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.
Read from SKILL.md and the folder at commit 1f7ac0f. It shows what the files ask for, not the result of running them.
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.
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.
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
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.
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.
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.
The full file from davidYichengWei/agentic-engineering-framework at commit 1f7ac0f, republished under its MIT licence (© davidYichengWei). 262 words, ~1,023 tokens.
.claude/skills/bp-component-design/SKILL.md (or your agent's skills folder).使用场景:
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 |
© davidYichengWei, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Just SKILL.md in skills/bp-component-design of davidYichengWei/agentic-engineering-framework.
Open the folder on GitHubat commit 1f7ac0f
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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Component Design Principles this skilldavidYichengWei/agentic-engineering-framework | 158 | — | ~1k | Automated safety check: Pass | MIT | |
| Brooks Audithyhmrright/brooks-lint | 1.5k | 1 repos | ~537 | Automated safety check: Pass | MIT | |
| Pattern Conformance AuditTotoro-jam/battle-tested-patterns | 345 | — | ~1.6k | Automated safety check: Pass | MIT | |
| Backend Code Reviewlanggenius/dify | 158k | — | ~676 | Automated safety check: Pass | Custom licence | |
| Code Review Skillawesome-skills/code-review-skill | 2.1k | — | ~2.8k | Automated safety check: Notes | MIT | |
| Architecture PatternsKartikLabhshetwar/better-shot | 2.4k | 2 repos | ~1.4k | Automated safety check: Pass | Custom licence |
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.
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.
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.
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…
KartikLabhshetwar/better-shot
Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.
pascalorg/editor
Reviews a pull request against the Pascal editor's architectural rules: package boundaries, registry-driven node composition, hook hygiene and selector performance.
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.
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.
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.
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.
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.
davidYichengWei/agentic-engineering-framework
代码文件修改的统一入口。当用户请求任何代码变更(新功能、优化、Bug 修复、重构)时必须首先调用此 skill。仅适用于代码文件(如 .cc/.cpp/.h/.go/.py 等),修改 .md 等非代码文件时不需要调用。它会评估复杂度、检查 spec.md、生成 tasks.md、并逐个任务执行。
Categories
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.
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.
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.
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.
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.
SKILL.md names no scripts, command-line tools or credentials: Component Design Principles is instructions for the agent only.
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.
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.
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.
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.
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.
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.