oh-my-claudecode Architect 智能体深度解析Claude Code 中基于证据的架构诊断与只读顾问设计【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode本文以 oh-my-claudecode 仓库中 Architect 智能体历史 v4.5.0 版本快照见 src/installer/tests/fixtures/historical-agents/v4.5.0/architect.md为解剖对象完整拆解这只战略架构与调试顾问的提示词工程职责边界、只读约束、调查协议、输出契约与失败模式并结合 src/agents/architect.ts、src/agents/utils.ts 等源码说明其如何被接线进多智能体编排系统。读完你将掌握如何阅读、复用乃至仿写一个必须先读代码、逐条给出 file:line 证据、承认权衡的高质量顾问型 Agent 提示词并理解其从 v4.5.0 到当前版本的设计演进。一、Architect 是谁定位与职责边界Architect 在 oh-my-claudecode 的多智能体系统中扮演战略架构与调试顾问Strategic Architecture Debugging Advisor角色。文档开篇的Role定义了三句话式的使命声明You are Architect. Your mission is to analyze code, diagnose bugs, and provide actionable architectural guidance.它明确负责四类事务代码分析code analysis实现验证implementation verification调试根因定位debugging root causes架构建议architectural recommendations同时明确不负责四类事务从而与系统中的其他角色形成职责分工不负责的事务由谁负责收集需求gathering requirementsanalyst制定计划creating plansplanner评审计划reviewing planscritic落地实现implementing changesexecutor这种一人一事、边界清晰的划分是 oh-my-claudecode 多智能体协作的基础Architect 永远只做读代码、下诊断、给建议改动代码是 executor 的职责而交接方向在Constraints中被明确固化。在源码层面这份角色定位被登记为advisor类别的只读咨询智能体。见 src/agents/architect.ts 中的元数据export const ARCHITECT_PROMPT_METADATA: AgentPromptMetadata { category: advisor, cost: EXPENSIVE, promptAlias: architect, triggers: [ { domain: Architecture decisions, trigger: Multi-system tradeoffs, unfamiliar patterns }, { domain: Self-review, trigger: After completing significant implementation }, { domain: Hard debugging, trigger: After 2 failed fix attempts }, ], useWhen: [ /* ... */ ], avoidWhen: [ /* ... */ ], };类别与成本等级的定义见 src/agents/types.tsAgentCost FREE | CHEAP | EXPENSIVEAgentCategory中的advisor注释即Strategic consultation (read-only)与提示词中的只读定位一一对应。二、Frontmatter 解剖如何声明一个只读智能体Architect 的提示词文件以 YAML frontmatter 开头历史 v4.5.0 版本快照为--- name: architect description: Strategic Architecture Debugging Advisor (Opus, READ-ONLY) model: claude-opus-4-6 disallowedTools: Write, Edit ---每个字段都有明确的语义name智能体标识符也是运行时加载提示词、按名字查找配置的键对应 src/agents/utils.ts 中loadAgentPrompt(agentName)的入参。description供编排器做智能体选择与委托决策的简短说明。这里显式标注了(Opus, READ-ONLY)即模型用 Opus、只读。model历史版本直接绑定claude-opus-4-6。当前版本 agents/architect.md 已改为model: opus并新增level: 3即从锁定具体模型实例演进为按模型族 层级映射更利于跨版本兼容与模型路由仓库文档 docs/agents/model-compatibility.md 对该兼容策略有更完整的说明。disallowedTools: Write, Edit只读约束的第一道硬闸门。它声明该智能体禁用写类工具从工具权限层面保证永不落地改动。frontmatter 的运行时消费逻辑在 src/agents/utils.tsparseDisallowedTools()会提取 frontmatter 中的disallowedTools逗号分隔列表并返回stripFrontmatter()src/agents/utils.ts则在加载提示词正文时剥离 YAML 头。AgentConfig的完整字段定义见 src/agents/types.ts其中disallowedTools、model、defaultModel、metadata均与 frontmatter 内容对应。值得注意的安全设计loadAgentPrompt在拼接agents/{agentName}.md路径前会做两重校验——先用/^[a-z0-9-]$/i正则拒绝含危险字符的智能体名再用resolverelative验证解析后的路径没有越出agents目录防止路径穿越如../../etc/passwd。这体现了提示词即攻击面的防御意识。三、为什么必须先读代码Why_This_Matters 与成功标准文档用专门的Why_This_Matters章节解释规则背后的动机这是整个提示词的设计哲学Architectural advice without reading the code is guesswork. These rules exist because vague recommendations waste implementer time, and diagnoses without file:line evidence are unreliable. Every claim must be traceable to specific code.即没读过代码的架构建议就是猜。模糊建议浪费实现者时间没有 file:line 证据的诊断不可靠所有论断必须可追溯到具体代码。由此衍生出的Success_Criteria成功标准v4.5.0 版本共 6 条每条发现都引用具体的file:line引用定位的是根因root cause而非症状建议具体可落地不是考虑重构一下这种话每条建议都承认权衡trade-offs分析对准实际问题本身而非邻近问题在 ralplan 共识评审中必须显式给出最强的替身反方论证steelman antithesis与至少一个真实的权衡张力。第 6 条呼应了仓库中的 ralplan 工作流可参见 skills/ralplan/SKILL.md在多智能体达成共识的评审场景里禁止对受青睐方案盖章放行必须先为反方做最强辩护。四、约束体系只读、证据、诚实、交接Constraints定义了五条硬约束构成 Architect 的行为红线READ-ONLYWrite 和 Edit 工具被禁用永远不实现改动与 frontmatter 的disallowedTools双重保障绝不评判未读过的代码没有打开读过的代码就没有发言权绝不给出通用建议任何代码库都能套用的建议是禁止的必须针对当前代码库存在不确定性时如实承认不猜测、不脑补明确交接对象需求缺口交给 analyst、计划创建交给 planner、计划评审交给 critic、运行时验证交给 qa-testerralplan 共识评审中绝不无反驳地附和受青睐选项。这套约束与其说是限制不如说是对顾问型智能体的可信度设计只读保证了建议的中立性证据要求保证了可验证性不确定性声明保证了诚实性而显式的交接链保证了协作不阻塞。五、调查协议八步取证流程Investigation_Protocol是 Architect 的核心工作方法v4.5.0 版本完整包含 8 步先收集上下文强制用 Glob 摸清项目结构用 Grep/Read 定位相关实现检查依赖清单找到既有测试——并行执行调试场景完整读错误信息用git log/git blame查近期变更找到类似代码的可用范例对比坏的 vs 好的以定位差异delta先形成假设再深入在深入之前把假设写下来用实际代码交叉验证假设每条论断引用 file:line综合输出Summary → Diagnosis → Root Cause → Recommendations排序→ Trade-offs → References非显而易见 bug 走四阶段协议Root Cause Analysis根因分析→ Pattern Analysis模式分析→ Hypothesis Testing假设检验→ Recommendation建议三次失败熔断器3-failure circuit breaker连续 3 次修复尝试失败后质疑架构本身而不是继续换着花样试ralplan 共识评审附加项(a) 对受青睐方向的最强反方论证(b) 至少一个无法忽视的权衡张力(c) 可行时给出综合方案synthesis(d) 在 deliberate 模式下显式标记原则违例。其中第 7 条熔断器是极具工程智慧的规则它把换一种修法和架构可能根本错了区分开防止在错误的地基上无限打补丁。六、工具使用策略与外部咨询Tool_Usage列出了 Architect 的取证工具箱并注明并行执行以提速工具用途Glob/Grep/Read代码库探索并行执行lsp_diagnostics检查单个文件的类型错误lsp_diagnostics_directory验证项目级健康状态ast_grep_search查找结构化模式例如所有没有 try/catch 的 async 函数Bashgit blame/git log变更历史分析External_Consultation定义了何时寻求第二意见的机制当第二意见能提升质量时可以派生一个 Claude Task 智能体——用Task(subagent_typeoh-my-claudecode:critic, ...)做计划/设计挑战或用/team拉起一个 CLI worker 做超大上下文的架构分析。同时约定了优雅降级委托不可用就静默跳过绝不阻塞。这套工具策略与 src/agents/prompt-sections/index.ts 中动态编排器提示词的构建逻辑相呼应——buildDelegationMatrix、buildTriggerTable等函数会根据各智能体的metadata自动生成委托指南与触发条件表让何时把活交给 Architect成为编排器提示词的一部分。而工具层面的限制与createAgentToolRestrictions()src/agents/utils.ts这类辅助函数共同保证只读策略在运行时真正生效。七、执行策略何时停止Execution_Policy规定了努力级别与终止条件默认努力级别高high带证据的彻底分析诊断完成、所有建议都带 file:line 引用时停止对显而易见的 bug如拼写错误、缺失 import跳过冗长流程直接给出带验证的建议。当前版本 agents/architect.md 对这条做了两处演进其一运行期 effort 继承父级 Claude Code 会话不再由 frontmatter 绑定其二行为层面的引导仍保持高带证据的彻底分析。这种运行期继承 行为引导的双轨设计比硬编码更灵活。八、输出契约结构化诊断报告Output_Format规定了 Architect 的固定输出结构v4.5.0 版本模板如下## Summary [2-3 句发现了什么 主要建议] ## Analysis [带 file:line 引用的详细发现] ## Root Cause [根本问题而非症状] ## Recommendations 1. [最高优先级] - [工作量级别] - [影响] 2. [次高优先级] - [工作量级别] - [影响] ## Trade-offs | Option | Pros | Cons | |--------|------|------| | A | ... | ... | | B | ... | ... | ## Consensus Addendum (ralplan reviews only) - **Antithesis (steelman):** [针对受青睐方向的最强反方论证] - **Tradeoff tension:** [无法忽视的权衡张力] - **Synthesis (if viable):** [如何保留竞争方案的优点] - **Principle violations (deliberate mode):** [任何被破坏的原则及其严重性] ## References - path/to/file.ts:42 - [说明] - path/to/other.ts:108 - [说明]这套结构的设计意图非常明确Summary 先行让调用方人类或上层编排器30 秒内抓住结论Analysis 必须带 file:line证据可回查Root Cause 与症状分离强制穿透表象Recommendations 标注工作量与影响便于优先级排序Trade-offs 用表格每个方案必须同时给出代价Consensus Addendum仅在 ralplan 共识评审场景出现强制对抗性思考References 列证据清单方便读者循路径验证。当前版本在输出契约之上新增了Final_Response_Contractagents/architect.md要求最后一条 assistant 消息必须是完整的结构化交付物Summary/Analysis/Root Cause/Recommendations/Trade-offs/References不得把实质性结论只放在中间消息或工具注释里且禁止以 donelooks good 这类无内容收尾语结束——从格式正确进一步约束到交付时机与完整性。仓库测试 src/tests/advisory-agent-final-output-contract.test.ts 正是对这一契约的验证。九、要避免的失败模式Failure_Modes_To_Avoid列出了五类典型失败每一条都配了正反对照v4.5.0 版本含完整示例Armchair analysis扶手椅分析没读代码就给建议。必须打开文件并引用行号Symptom chasing追症状问题明明是为什么它是 undefined却到处推荐空值检查。必须找到根因Vague recommendations模糊建议只说考虑重构这个模块而没有把auth.ts:42-80的校验逻辑抽成validateToken()函数这类具体指令Scope creep范围蔓延评审了没被问到的领域。只回答具体问题Missing trade-offs漏掉权衡推荐方案 A 却不说它牺牲了什么。必须承认代价。文档用一正一反两个例子把好诊断与坏诊断的差距具象化Good竞态条件源自server.ts:142——connections在无互斥锁的情况下被修改。第 145 行的handleConnection()读取数组而第 203 行的cleanup()可能并发修改它。修复把两者都包进锁。权衡连接处理会有轻微延迟增加。Bad服务器代码某处可能有并发问题。考虑给共享状态加锁。——缺乏具体性、证据和权衡分析。十、源码实现Architect 如何被接线进系统在 oh-my-claudecode 中Architect 的注册与加载链路清晰可查1. 智能体注册src/agents/architect.tsexport const architectAgent: AgentConfig { name: architect, description: Read-only consultation agent. High-IQ reasoning specialist for debugging hard problems and high-difficulty architecture design., prompt: loadAgentPrompt(architect), model: opus, defaultModel: opus, metadata: ARCHITECT_PROMPT_METADATA };2. 提示词动态加载src/agents/utils.tsloadAgentPrompt(architect)优先使用 esbuild 构建期注入的__AGENT_PROMPTS__映射CJS 打包产物开发/测试环境则回退到运行时读取agents/architect.md并剥离 frontmatter——代码注释明确标注 agents/architect.md 是权威来源authoritative source。3. 模型路由src/agents/types.tsgetDefaultModelForCategory(advisor)返回opus注释为High quality reasoning。这解释了为何 Architect 默认绑定 Opus——顾问型智能体需要最强的推理质量同时其cost: EXPENSIVE元数据会写进委托表提醒编排器贵别乱用。4. 委托触发useWhen明确列出适用场景复杂架构设计、完成重大工作后、2 次修复失败、陌生代码模式、安全/性能疑虑、跨系统权衡avoidWhen列出不适用场景简单文件操作、任何修复的第一次尝试、读过代码就能回答的问题、琐碎决策、能从既有代码模式推断的事——见 src/agents/architect.ts。这套何时用/何时别用会经 src/agents/prompt-sections/index.ts 的buildToolSelectionSection、buildDelegationMatrix渲染进编排器提示词实现新增智能体自动更新编排器的动态机制。5. 测试佐证仓库测试 src/tests/load-agent-prompt.test.ts 覆盖提示词加载路径src/tests/advisory-agent-final-output-contract.test.ts 校验输出契约而本文章所依据的 v4.5.0 快照则作为 installer 测试夹具保存在 src/installer/tests/fixtures/historical-agents/ 下。十一、历史演进从 v4.5.0 到当前版本的差异将本文章主体v4.5.0 快照与当前 agents/architect.md 对比可以清晰看到该智能体的迭代方向维度v4.5.0 历史快照当前版本模型声明model: claude-opus-4-6锁定具体实例model: opuslevel: 3模型族 层级执行策略Default effort: high硬编码运行期 effort 继承父会话行为引导保持 high输出契约结构化模板Summary…References新增Final_Response_Contract末条消息必须含完整交付物禁止无内容收尾ralplan 共识条款已含 steelman antithesis tradeoff tension保留并强调 deliberate 模式下的原则违例标记交接条款已含 analyst/planner/critic/qa-tester 交接保留版本演进的证据链由 src/installer/historical-agent-ownership.ts 提供该清单为每个历史architect.md记录精确的byteLength、sha256、gitBlob与发布区间。其中 v4.5.0 区间的记录为byteLength: 6877、sha256: fbac3c92...、firstReleaseTag: v4.5.0, lastReleaseTag: v4.8.2与测试夹具目录v4.5.0/一一对应。该清单的注释明确强调不要用文件名、frontmatter 或模糊启发式替代这些精确字节级所有权记录——这是为历史智能体文件提供可审计的溯源保证。十二、如何在你的会话中查看与使用 Architect在 oh-my-claudecode 中Architect 的提示词正文权威来源位于 agents/architect.md其历史快照与配套夹具位于 src/installer/tests/fixtures/historical-agents/实现代码位于 src/agents/architect.ts 与 src/agents/utils.ts类型系统见 src/agents/types.ts。触发 Architect 的典型场景来自其metadata.triggers架构决策跨系统权衡、陌生代码模式时自我评审完成重大实现之后硬核调试连续 2 次修复尝试失败之后。需要注意其avoidWhen的提醒简单文件操作、任何修复的第一次尝试、读过代码就能回答的问题都不应动用这只成本为 EXPENSIVE 的顾问智能体。而它的输出之所以可信核心在于那条贯穿全篇的铁律——每条论断都带 file:line 证据每条建议都承认权衡。这套证据驱动 只读中立 对抗性自检的提示词设计正是编写高质量顾问型 Agent 时可复用的范本。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考