菜单
Explain the reasoning behind SBP engineering conventions — connect rules to real failure modes, show the trade-offs, and make the case with concrete examples. Use when an engineer asks why a convention exists or when onboarding new team members.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | sbp-why-we-do-this |
| description | Explain the reasoning behind SBP engineering conventions — connect rules to real failure modes, show the trade-offs, and make the case with concrete examples. Use when an engineer asks why a convention exists or when onboarding new team members. |
| metadata | {"domain":"cross-cutting","lifecycle":"cross-cutting"} |
When an engineer asks "why do we do it this way?", give them the real answer — not "because the rules say so" but "because here is what goes wrong without it."
Every convention at SBP exists because something broke, something almost broke, or the cost of it breaking in a mission-critical environment is unacceptable. Explain the reasoning honestly, including the trade-offs.
Follow this structure:
What it prevents: A dependency update introducing breaking changes or malicious code into a production system without explicit review.
What breaks without it: A package maintainer pushes a compromised version. Every build that runs pip install package>=1.0 picks it up automatically. Your next deploy ships malicious code to production without any engineer reviewing or approving the change. This is not theoretical — the event-stream, ua-parser-js, and colors.js incidents all exploited version ranges.
Trade-off: You have to manually update dependencies and test them. Dependabot or Renovate can automate the PR creation, but a human still reviews it.
Why it is worth it: In mission-critical systems, predictability beats convenience. You want to know exactly what is running in production, and you want every change to be deliberate.
What it prevents: Slow, non-reproducible dependency resolution that produces different results on different machines.
What breaks without it: pip resolves dependencies at install time with no lockfile by default. Two engineers run pip install -r requirements.txt on the same day and get different transitive dependency versions. One works, one does not. CI produces a different result than local. You spend hours debugging "works on my machine" problems that are actually dependency resolution differences.
Trade-off: Engineers need to learn a new tool. The uv CLI is deliberately similar to pip, so the learning curve is minimal.
Why it is worth it: uv is deterministic, fast (10-100x faster than pip), and produces lockfiles that guarantee reproducibility. In mission-critical systems, "it worked on my machine" is not an acceptable deployment strategy.
What it prevents: Inconsistent formatting, linting gaps, slow CI feedback, and configuration drift between multiple tools.
What breaks without it: With three separate tools, each has its own configuration file, its own version, and its own opinion. They occasionally conflict (black reformats something that isort then reformats back). CI takes 30+ seconds to run all three. Engineers disable one tool because it is slow and miss real issues.
Trade-off: Ruff is newer and has fewer edge-case rules than the combined ecosystem. Some very niche flake8 plugins do not have ruff equivalents yet.
Why it is worth it: One tool, one config file, sub-second execution, consistent results. Engineers actually run it because it is fast. The best linter is the one that runs, not the one with the most rules.
What it prevents: Runtime type errors in production, unclear interfaces, and costly debugging sessions.
What breaks without it: A function accepts a dict but someone passes a list. In a typed codebase, the IDE and mypy catch this before the code leaves the engineer's machine. In an untyped codebase, it passes review, passes tests that happen to use the right type, and crashes at 2 AM when a rare code path runs for the first time.
Trade-off: Writing type hints takes time, especially for complex types. Some dynamic Python patterns are hard to type correctly.
Why it is worth it: Types are documentation that the machine verifies. In mission-critical systems, "I think this function takes a string" is not good enough. Types make code reviewable, refactorable, and debuggable by engineers who did not write it.
What it prevents: Deploying changes that cannot be undone when they cause problems.
What breaks without it: An engineer deploys a database migration that drops a column. The new code has a bug. You need to roll back the code, but the old code depends on the column that no longer exists. Now you have a broken production system with no clear path to recovery. A 5-minute rollback becomes a 4-hour emergency.
Trade-off: Writing and testing rollback plans takes time. Some changes require creative rollback strategies (forward-fix instead of revert, compatibility windows for schema changes).
Why it is worth it: The rollback plan is your insurance policy. You hope you never need it, but when you do, it is the difference between a 5-minute recovery and a multi-hour incident. In mission-critical systems, "we will figure it out if something goes wrong" is not a plan.
What it prevents: Making changes that affect more systems, customers, or data than intended.
What breaks without it: An engineer updates a shared library and deploys it. They tested it with their service. But the library is used by 12 other services, three of which use an API that changed subtly. Those three services start returning errors. The engineer who made the change does not even know those services exist.
Trade-off: Blast radius analysis takes time and requires understanding the system topology. For large changes, it can take as long as the change itself.
Why it is worth it: Blast radius analysis is how you find out what you do not know before production finds out for you. Most major incidents start with "we did not realize this would affect X."
If an engineer thinks a convention is unnecessary overhead:
If an engineer is new to SBP and encountering these conventions for the first time:
Some conventions are annoying and still necessary. Be honest about it.
"Yes, writing a rollback plan for a one-line config change feels like overkill. And 99% of the time, it is. But the 1% where the config change breaks authentication and you need to revert in 30 seconds — that is the scenario the rollback plan exists for. The annoyance is the cost; the insurance is the benefit."
Honesty about trade-offs builds more trust than pretending everything is perfectly efficient.
Use when building any UI, HTML component, slide, document, or design asset that will represent SBP visually — applies the Schuberg Philis visual brand identity (colors, typography, logo, stylization, grids, photography, iconography) to ensure brand-consistent output without manual reminders.
Use when conducting a security review, reducing dependency surface, or when dependencies may pose supply-chain, bloat, or maintainability risks.
Use when deploying to production — verifies rollback readiness, monitoring, and change communication against mission-critical criteria and produces a go/no-go decision.
Use when a production incident has occurred — structured blameless post-incident analysis that reconstructs timeline, assesses impact, finds root causes, and produces concrete action items.
Use when verifying monitoring, alerting, and logging coverage — checks the four pillars (metrics, logs, traces, alerts), produces a coverage matrix with gaps, severity ratings, and recommended actions, and applies the 3 AM test to every component.
Use when existing code needs to change shape before a feature, or when code drift is making further work expensive — improves structure and readability without changing observable behavior.
