architecting-solutions

architecting-solutions 技能概览

architecting-solutions 是做什么的

architecting-solutions 是一个面向 Claude Code 的结构化架构与解决方案设计工作流。它的目标，是把诸如“设计一个计费系统”或“规划一次迁移”这类较为模糊的需求，沉淀为更完整的技术设计：包括澄清后的需求、关键权衡，以及一份写入项目 docs/ 目录的书面输出。

谁适合使用 architecting-solutions

这个技能最适合工程师、tech lead、staff engineer，以及依赖 AI 协作构建系统的开发者；如果你需要的不只是泛泛而谈的 brainstorm，而是更成体系的设计输出，它会很合适。典型适用场景包括系统设计、迁移规划、重构、功能架构设计，以及需要明确约束和形成文档结论的 Requirements Planning。

它真正解决的是什么问题

用户通常希望通过它达成三类结果之一：

1. 把模糊需求转成可执行的技术方案，
2. 对多个方案进行有权衡的比较，
3. 留下一份可复用、适合后续实现的 PRD 风格架构文档。

正因为如此，当项目上下文很重要时，architecting-solutions 会比一次性的“帮我设计这个系统”提示词更有价值。

相比普通提示词，architecting-solutions 的关键差异

architecting-solutions 的核心价值在于它对流程的约束力：

• 它会先澄清需求，
• 会分析现有代码库中的模式和约束，
• 输出的是一份正式文档，而不只是聊天回答，
• 并且会明确把结果写入 docs/。

这里有一个值得注意的细节：仓库说明提到，如果请求里明确写了 PRD，就不要把它当作 PRD 专用技能来用；但这个技能本身又确实会生成 PRD 风格的输出。实际使用中，它最适合的是带有实现上下文的技术设计和 Requirements Planning，而不是纯产品探索。

什么情况下 architecting-solutions 特别适合

在以下需求中，优先考虑使用 architecting-solutions：

• 为新功能或子系统做架构设计，
• 做迁移规划或重构规划，
• 基于现有代码库输出技术设计，
• 需要比较多个方案并分析 trade-off，
• 做 architecting-solutions for Requirements Planning，且技术范围与约束会显著影响结论。

什么情况下不该用这个技能

如果你只需要以下内容，就不建议使用 architecting-solutions：

• 轻量级 brainstorm，
• 没有架构深度、纯产品导向的 PRD，
• bug 修复方案，
• 不涉及设计工作的代码生成，
• 主要取决于业务优先级、而非技术约束的决策。

如何使用 architecting-solutions 技能

安装来源与仓库路径

这个技能位于 zhaono1/agent-playbook 仓库中的 skills/architecting-solutions。

一个实用的安装命令是：
npx skills add https://github.com/zhaono1/agent-playbook --skill architecting-solutions

技能文档还提到，典型的安装路径通常是：
~/.claude/skills/architecting-solutions/

建议先读哪些文件

如果你想快速判断它是否适合，建议按这个顺序阅读：

1. skills/architecting-solutions/SKILL.md
2. skills/architecting-solutions/README.md

其中 SKILL.md 包含了大部分实际使用细节：触发条件、工作流、允许使用的工具，以及必须把输出写入 docs/ 的要求。

architecting-solutions 在实际中如何触发

仓库里的示例提示都很直接，是自然语言请求，例如：

• “Design solution for a new billing system”
• “Provide an architecture design for multi-tenant analytics”
• “Technical design for a data migration plan”

这意味着，architecting-solutions usage 更偏向由提示意图触发，而不是依赖复杂命令。只要你的意图是方案设计、架构设计、技术设计、迁移规划，或功能级技术规划，就基本符合触发条件。

哪些输入能明显提升输出质量

如果你提供以下信息，技能效果会明显更好：

• 系统目标，
• 用户或负载类型，
• 硬性约束，
• 现有技术栈，
• 非功能性需求，
• 交付边界。

一个好的输入示例：
“Use architecting-solutions to design a multi-tenant analytics ingestion service for our Node.js/Postgres stack. We ingest 50M events/day, need tenant isolation, 99.9% uptime, GDPR deletion support, and rollout in two phases without breaking current APIs.”

之所以这个输入有效，是因为它给出了规模、技术栈、约束、可靠性目标和发布限制，而这些正是会直接影响架构决策的关键信息。

如何把模糊需求改写成高质量提示词

较弱的写法：
“Design an analytics system.”

更强的写法：
“Use architecting-solutions to propose 2 architecture options for a multi-tenant analytics platform in our existing Python + Kafka + ClickHouse environment. Include ingestion, storage, query path, tenant isolation, observability, and migration risk. Recommend one option and write the final design to docs/analytics-architecture.md.”

更强的版本能显著提升方案质量、比较深度，以及最终输出格式的可用性。

面向真实项目的推荐工作流

一个实用的 architecting-solutions guide 可以这样执行：

1. 先给出问题陈述，
2. 让技能先提出澄清问题，
3. 指明需要查看的仓库区域，
4. 强制比较 2–3 个方案并明确 trade-off，
5. 要求给出推荐方案，
6. 让它把最终 markdown 写入 docs/，
7. 在实现开始前先审查缺口。

这对 Requirements Planning 尤其有用，因为它能把需求探索、约束识别和最终设计拆开处理，而不是糅成一个笼统回答。

这个技能有哪些明确偏好

从仓库层面看，它最明确的偏好就是输出位置：最终的 PRD 风格文档应写入 {PROJECT_ROOT}/docs/，而不是隐藏文件或临时规划笔记。如果你们团队把设计文档放在别处，最好一开始就说清楚，避免 agent 默认写到文档中约定的路径。

让设计真正结合代码库的最佳提示方式

如果你已经打开了仓库，最好明确告诉它该看哪些内容：
“Use architecting-solutions for Requirements Planning on our auth overhaul. Review services/auth/, docs/current-architecture.md, and infra/terraform/ first. Match existing deployment patterns unless there is a strong reason not to.”

这很重要，因为这个技能本来就是按“先分析上下文和现有模式，再提出方案”的思路设计的。

你可以预期的输出形态

根据它的工作流，architecting-solutions 通常会产出：

• 需求澄清，
• 上下文与约束分析，
• 建议架构，
• trade-off 分析，
• 面向实现的 markdown 文档。

如果你只想要一个轻量回答，可以直接说明；否则它默认更偏向“先形成文档”，而不是快速聊天式建议。

常见采用障碍

最大的障碍通常是范围不清。如果你只说“做个架构”，却不说明约束，输出就很容易变得泛化。在评价这个技能之前，先用一条包含明确规模、系统边界，以及至少一个硬性 trade-off 的请求来测试它，比如成本 vs 速度、一致性 vs 延迟、复用 vs 重写。

architecting-solutions 技能 FAQ

architecting-solutions 适合新手吗？

适合，但前提是新手对自己所在系统已经有基本认知。这个工作流能通过强制澄清和结构化思考来提供帮助。不过，新手往往仍然不容易判断 trade-off 是否合理，所以最佳使用方式仍然是配合更有经验的工程师做人工评审。

它到底是 PRD 技能，还是架构技能？

从实际使用上看，两者都有，但架构优先。仓库元数据把 architecting-solutions 定位为技术方案与架构技能，而它的工作流又会输出一份 PRD 风格的 markdown 文档。适合在“文档由技术设计驱动”的情况下使用；如果你要的是纯产品管理视角的 PRD，它就不是最匹配的工具。

architecting-solutions 和普通的“设计一下这个系统”提示有什么区别？

普通提示词常常会返回一份写得漂亮、但上下文偏弱的答案。architecting-solutions skill 更适合需要可重复流程的场景：先澄清需求，再检查代码库，再比较方案，最后产出并保存设计文档。

architecting-solutions 安装时会附带额外工具吗？

不会。这里看不到额外的 helper script 或资源目录。architecting-solutions install 的重点，主要是从 agent-playbook 仓库添加这个技能，然后在 Claude Code 中结合合适的提示词和仓库上下文来调用它。

我可以把 architecting-solutions 用于 Requirements Planning 吗？

可以。architecting-solutions for Requirements Planning 在以下场景非常合适：需求会受到技术约束、迁移现实或架构选型的明显影响。相对地，如果你处在早期市场验证阶段，或只是做纯业务侧需求起草，那它就不太适合。

什么情况下不该用 architecting-solutions？

以下场景建议跳过：

• 产品策略备忘录，
• 简短的实现检查清单，
• 调试协助，
• 只要代码、不需要设计的回答，
• 不包含架构分析的 PRD。

如何改进 architecting-solutions 的使用效果

与其给大目标，不如给更强的约束

提升 architecting-solutions 结果质量的最好方法，不是把目标说得更宏大，而是补充真正驱动设计的约束：

• 流量规模，
• 延迟目标，
• 合规需求，
• 部署环境，
• 向后兼容要求，
• 成本上限，
• 时间节点。

相比“scalable”或“robust”这种泛泛目标，这类输入更能逼出有区分度的 trade-off。

先让它给方案选项，再让它下结论

如果第一次回答显得过窄，可以明确要求：
“Give me 2–3 viable architectures first, with trade-offs and failure risks, before writing the final recommendation.”

这样可以避免技能过早收敛到单一模式上。

明确告诉技能该看哪些代码和文档

一个常见失败模式，是给出的架构忽略了本地约定。要改善输出，最好直接点名具体路径：

• services/
• apps/
• docs/
• infra/
• 当前的 ADR 或设计文档

对于已有系统，这通常比在提示词里多写几段泛泛描述更重要。

把输出产物说清楚

如果你希望得到一份可复用文档，就明确文件名和目标读者：
“Write the final design to docs/payment-migration.md for backend engineers and reviewers.”

这既符合技能文档中的行为约定，也能减少它在格式和深度上的歧义。

用有针对性的追问修正泛化初稿

第一版出来后，不要只说“改得更好一点”。更有效的做法是提出明确补强项：

• 增加运维风险，
• 比较迁移策略，
• 补充回滚方案，
• 展示数据模型影响，
• 按团队梳理依赖关系，
• 标出仍需验证的未知项。

这种有针对性的迭代，通常比把整个提示词重跑一遍更快把文档拉到可用水平。

重点留意最大的失败风险

architecting-solutions 最常见的质量风险包括：

• 约束描述不足，
• 架构方案脱离真实代码库，
• 推荐结论过于自信，但 trade-off 分析很弱，
• 产出的 PRD 风格文档过于宽泛，不够支撑实现规划。

通常只要补上 repo 路径、硬性约束，以及强制要求比较章节，就能把这四类问题纠正回来。

用评审回路提升 architecting-solutions

最佳工作方式通常是两轮：

1. 先用 architecting-solutions 产出初版设计，
2. 再审查其中缺失的约束，并主动挑战推荐结论。

可以继续追问：

• “What assumptions would most likely break this design?”
• “What is the cheapest acceptable version?”
• “What changes if we optimize for 3-month delivery instead of long-term scale?”

这样一来，这个技能就不只是一个文档生成器，而会变成真正实用的设计评审助手。