Back to Details

study-design-verify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Study → Design → Verify

Study → Design → Verify

Turn "how should this work?" into a recommendation that survives scrutiny, by separating three jobs that corrupt each other when one mind does them at once: gathering facts, proposing designs, and attacking designs. Each phase is staffed by agents who only do that one job.
The output is an advisory document: problems ranked by business pain, a phased plan, explicit "do NOT do X because Y" entries, and an evidence trail a skeptic can audit.
将「这应该如何运作？」转化为经得起推敲的推荐方案，方法是将单个主体同时执行时会互相干扰的三项工作分离：收集事实、提出设计方案、校验设计方案。每个阶段由仅负责该工作的Agent组成。
输出结果为一份咨询文档：按业务痛点排序的问题列表、分阶段计划、明确的「请勿执行X，原因是Y」条目，以及可供质疑者审核的证据链。

When to invoke

触发场景

"How should A convert/map/migrate/sync to B?" · "study my business, then advise" · "what's the right design for [change to an existing system]?" · "should we copy, link, or recalculate this data?" · "review this integration plan against reality" · build-vs-extend questions about an existing flow. If the answer should change when the real system contradicts the docs, this skill applies.
「A应如何转换/映射/迁移/同步至B？」·「研究我的业务并给出建议」·「[现有系统变更]的正确设计是什么？」·「我们应复制、链接还是重新计算这些数据？」·「对照实际情况审查此集成计划」· 关于现有流程的自建vs扩展类问题。如果当真实系统与文档不符时答案需要改变，则适用此技能。

Principles (the why)

核心原则（设计初衷）

  1. Conclusions, not raw text. One context window can't hold the wiki, two codebases, and a live schema. Fan out readers with fresh contexts; keep only their structured findings. You are the orchestrator, not the reader.
  2. Structured findings beat prose. Force every reader through a JSON schema (
    summary
    , 
    keyFindings
    with citations, 
    openQuestions
    ). Schema-shaped facts can be merged, diffed, and verified; prose can only be trusted.
  3. The live system outranks the docs. Documentation states conventions; only the live system shows whether they're implemented. Real example of the failure mode: a documented "placeholder records are kept Inactive" convention where every live placeholder was Active — two of three designs built on the fiction. Always check the convention, not just the doc.
  4. Usage data settles arguments. "Is bucket X dead?" / "does anyone use field Y?" are queries, not opinions. A design that maps into a never-used category, or drops a heavily-used one, is wrong in a way only live counts reveal. Every number in the study carries the query that produced it.
  5. Independent designs beat one design iterated. Designers who can see each other converge on shared blind spots. Give the same study digest to designers with conflicting value systems and let the differences surface the real trade-offs.
  6. Plausible-but-wrong is THE failure mode of AI advice. Designs reference fields that don't exist, assume single sources of truth that are actually duplicated, and inherit errors from the study digest. The adversarial pass is not optional polish — in practice it catches wrong field sources, misdescribed value lists, and unimplemented conventions in every run.
  7. Read-only, with receipts. A study never writes to a live system — GET/SELECT only, stated as a hard rule in every agent prompt. Raw query output is saved to an evidence folder (
    tmp/advice-study/
    or similar) so a human can audit what was looked at.
  1. 结论优先，而非原始文本。单个上下文窗口无法容纳维基文档、两个代码库及实时模式。将读取任务分发至拥有全新上下文的多个读取器；仅保留其结构化发现。你是协调者，而非读取者。
  2. 结构化发现优于散文式描述。强制每个读取器遵循JSON schema（包含
    summary
    、带引用的
    keyFindings
    、
    openQuestions
    ）。符合schema的事实可被合并、对比和校验；散文式描述仅能依赖信任。
  3. 实时系统优先级高于文档。文档仅说明约定；只有实时系统能展示这些约定是否已落地。失败模式实例：文档规定「占位记录需保持Inactive状态」，但所有实时占位记录均为Active——基于错误假设的设计占三分之二。务必检查实际约定，而非仅依赖文档。
  4. 使用数据解决争议。「存储桶X是否已废弃？」/「是否有人使用字段Y？」是查询问题，而非主观意见。若设计映射至从未使用的分类，或丢弃高频使用的分类，这种错误只有实时数据统计才能揭示。研究中的每个数据都附带生成它的查询语句。
  5. 独立设计优于单一设计迭代。能互相看到彼此方案的设计师会收敛于共同的盲区。向秉持冲突价值体系的设计师提供相同的研究摘要，让差异凸显真实的权衡取舍。
  6. 看似合理实则错误是AI建议的典型失败模式。设计方案可能引用不存在的字段、假设实际为重复的单一数据源、继承研究摘要中的错误。对抗性校验并非可选的优化步骤——实践中，它在每次运行时都会捕获错误的字段来源、描述错误的取值列表及未落地的约定。
  7. 只读操作，留痕可查。研究阶段绝不写入实时系统——仅允许GET/SELECT操作，且在每个Agent的提示词中明确此硬性规则。原始查询输出保存至证据文件夹（如
    tmp/advice-study/
    ），以便人工审核查看过的内容。

Phase 0 — Scope and scout (inline, before any fan-out)

阶段0——范围界定与探查（内联执行，在任何任务分发前完成）

Do this yourself; it's cheap and determines everything downstream.
  1. Pin the question into the form "how should [source thing] become / drive / map to [target thing]?" — with the user's actual pain named (what confused or hurt them).
  2. Establish current state. If how-it-works-today isn't already verified, run a current-state audit first (parallel readers + one verifier) and write it down. You cannot advise on changing a mechanism you haven't verified.
  3. Inventory the evidence sources. The standard five — adapt to what exists:
    • Domain/business context — wiki, specs, ADRs, onboarding docs. Why is the system shaped this way; who consumes what.
    • Target-side structure — live schema/contract of the thing being written to (DB tables, entity metadata, API spec, config).
    • Source-side structure — live schema of the thing being read from, plus its adjacent machinery (rules engines, pricing tables, queues).
    • Usage patterns — live counts and distributions: which values/categories/paths are actually used, which links are actually populated.
    • The comparison flow — how does the native, legacy, or competing path do the same job? It encodes domain decisions the new design should honor or consciously reject.
  4. Verify access before fanning out. One inline auth test against the live system (a 
    WhoAmI
    , a 
    SELECT 1
    ). Five agents failing on auth in parallel wastes a fan-out.
  5. Confirm the environment you're about to study (URL/connection string shown to the user) if there's any multi-environment ambiguity. Findings from the wrong environment are worse than no findings.
此步骤由你亲自完成；成本低且决定了后续所有流程。
  1. 明确问题，将其转化为*「[源对象]应如何转变为/驱动/映射至[目标对象]？」*的形式——同时明确用户的实际痛点（是什么困扰或伤害了他们）。
  2. 确认当前状态。若当前运作机制尚未验证，需先执行当前状态审计（并行读取器+一个校验器）并记录结果。你无法针对未验证的机制提供变更建议。
  3. 盘点证据来源。标准来源有五类——可根据实际情况调整：
    • 领域/业务上下文——维基文档、规格说明、ADRs、入职文档。系统为何是当前形态；谁在使用什么内容。
    • 目标端结构——待写入对象的实时模式/契约（数据库表、实体元数据、API规格、配置）。
    • 源端结构——待读取对象的实时模式，及其相关机制（规则引擎、定价表、队列）。
    • 使用模式——实时统计数据与分布：哪些取值/分类/路径实际被使用，哪些链接实际已填充。
    • 对比流程——原生、遗留或竞品路径如何完成相同任务？它包含新设计应遵循或有意识拒绝的领域决策。
  4. 任务分发前验证访问权限。对内联执行一次针对实时系统的权限测试（如
    WhoAmI
    、
    SELECT 1
    ）。五个Agent因权限问题并行失败会浪费任务分发资源。
  5. 确认研究环境（向用户展示URL/连接字符串），若存在多环境歧义时必须执行。错误环境的研究结果比无结果更糟。

Phase 1 — Study (parallel readers, one per evidence source)

阶段1——研究（并行读取器，每个证据来源对应一个）

Spawn one reader per source from the inventory, all in parallel. Each prompt contains:
  • The pinned question and the verified current state (so readers know what matters).
  • Its specific file paths / endpoints / entity names — scout these in Phase 0; don't make readers guess.
  • The read-only rule and the evidence folder path, verbatim, for anything live.
  • Platform gotchas you already know (quirky filters, encoding rules, rate limits) — agents rediscovering known gotchas is pure waste.
  • The findings schema (see 
    references/workflow-template.md
    ).
Precise questions beat broad mandates: "does the target entity have ANY link back to the source entity — check all lookup/FK attributes" outperforms "study the target schema."
Then merge mechanically into one digest (concatenate the structured findings). No agent needed.
为每个盘点出的来源生成一个读取器，所有读取器并行执行。每个提示词包含：
  • 明确后的问题及已验证的当前状态（让读取器了解重点）。
  • 具体的文件路径/端点/实体名称——在阶段0中探查这些信息；不要让读取器猜测。
  • 只读规则和证据文件夹路径，对于实时系统需逐字说明。
  • 你已知的平台陷阱（特殊过滤器、编码规则、速率限制）——让Agent重新发现已知陷阱纯粹是浪费资源。
  • 发现结果的schema（参见
    references/workflow-template.md
    ）。
精准问题优于宽泛指令：「目标实体是否存在任何指向源实体的链接——检查所有lookup/FK属性」的效果远好于「研究目标模式」。
然后自动合并为一份摘要（拼接结构化发现结果）。无需Agent参与。

Phase 2 — Design panel (independent, conflicting value systems)

阶段2——设计小组（独立运作，价值体系冲突）

Give the same digest to 3 designers who cannot see each other. Default lenses — rename to fit the domain:
LensOptimizes forCharacteristic move
Fidelity-firstNo information entered upstream may be lost downstream; full traceabilityAdds columns/links; accepts schema growth
Consumer-firstWhat the downstream process actually consumes (capacity math, billing, search…)Maps into the correct existing buckets; rejects new categories that break consumers
Minimal-change pragmatistSmallest change that removes the worst pain, ranked by live-data evidencePhases everything; prefers code-only over schema; quantifies pain ("breakbulk is 0.8% of lines")
Swap lenses when the domain demands it (reliability/cost for infra, consistency/a11y for UX). Three is the sweet spot — two gives a false binary, five repeats itself.
Each designer must: ground every mapping in fields the study proved exist or explicitly flag as NEW; give exact transform rules (no "handle appropriately"); cover the awkward topics (what's dropped, what's defaulted, idempotency/retries); and answer the user's specific sub-questions (e.g. "what happens to the surcharges?") in a dedicated field of the design schema.
将相同的研究摘要提供给3个无法互相查看的设计师。默认视角——可根据领域调整名称：
视角优化目标典型做法
保真优先上游输入的信息不得在下游丢失；具备完整可追溯性添加列/链接；接受模式扩展
消费者优先下游流程实际需要的内容（容量计算、计费、搜索……）映射至正确的现有分类；拒绝会破坏消费者的新分类
最小变更实用主义能消除最严重痛点的最小变更，基于实时数据证据排序分阶段推进所有事项；优先选择仅修改代码而非模式；量化痛点（如「散货占比0.8%」）
可根据领域需求替换视角（如基础设施领域可替换为可靠性/成本，UX领域可替换为一致性/a11y）。三个视角是最优选择——两个会形成虚假二元对立，五个会重复冗余。
每个设计师必须：所有映射均基于研究证明存在的字段，或明确标记为NEW；给出精确的转换规则（不得出现「适当处理」）；覆盖棘手问题（丢弃什么、默认值是什么、幂等性/重试机制）；在设计schema的专用字段中回答用户的具体子问题（如「附加费如何处理？」）。

Phase 3 — Adversarial feasibility (attack, then recommend)

阶段3——对抗性可行性校验（攻击，然后推荐）

One reviewer, whose only job is to break the designs. It must re-verify primary sources itself — re-open the code, re-query the live schema (read-only) — not just re-read the digest, because the digest itself may carry errors into all three designs. Attack checklist:
  • Existence: does every referenced field/endpoint/value actually exist in the live system? (The most common kill: a design snapshots a total from a field that doesn't exist.)
  • Breakage: what existing consumers — jobs, dashboards, state machines, capacity math, pickers — read the things being changed? Verify in code, not by intuition.
  • Data consistency: do live distributions support the mapping? Are "dead" categories actually dead? Are "always populated" links actually populated?
  • Unimplemented conventions: which documented conventions does the design rely on that the live system contradicts?
  • Where changes really land: the file/layer a design names is often not where the behavior actually lives — verify the exact decision point.
Output per design: verified-OK list, problems with evidence, concrete fixes. Plus cross-cutting corrections (digest errors affecting all designs) and a recommendation: which design — or hybrid — survives, with which fixes applied.
设置一个审查者，其唯一任务是找出设计方案的问题。它必须自行重新验证原始来源——重新查看代码、重新查询实时模式（只读）——而非仅重新阅读研究摘要，因为摘要本身可能携带错误并传递给所有三个设计方案。攻击检查清单：
  • 存在性：每个引用的字段/端点/取值是否真的存在于实时系统中？（最常见的致命问题：设计方案从不存在的字段中提取汇总数据。）
  • 破坏性：哪些现有消费者——作业、仪表盘、状态机、容量计算、选择器——会读取被修改的内容？需在代码中验证，而非凭直觉判断。
  • 数据一致性：实时数据分布是否支持该映射？「已废弃」的分类是否真的无人使用？「始终填充」的链接是否真的已填充？
  • 未落地的约定：设计方案依赖的哪些文档约定与实时系统不符？
  • 变更实际落地位置：设计方案提及的文件/层往往并非行为实际发生的位置——需验证确切的决策点。
每个设计方案的输出：已验证通过的列表、带证据的问题、具体修复方案。此外还需包含跨设计方案的修正（影响所有设计的摘要错误）及推荐意见：哪个设计方案——或混合方案——经修复后可采用。

Phase 4 — Synthesize and deliver (you, in the main context)

阶段4——合成与交付（由你在主上下文中完成）

Don't delegate this — judgment about the user's context lives with you.
  1. Adopt the reviewer's recommendation unless you can articulate why not; apply every correction it found (each one was a falsehood about to be shipped as advice).
  2. Write the advisory in this shape:
markdown
undefined
请勿委派此步骤——关于用户上下文的判断需由你完成。
  1. 采纳审查者的推荐意见，除非你能明确说明不采纳的理由；应用它发现的所有修正（每个修正都是即将作为建议输出的错误信息）。
  2. 按以下结构撰写咨询文档：
markdown
undefined

The N problems worth fixing, ranked by pain ← business consequence first, mechanism second

值得修复的N个问题，按痛点排序 ← 优先考虑业务影响，其次是机制问题

Phase 1 — [quick wins] ← small schema/code, kills the worst pain

阶段1——[快速见效的方案] ← 小型模式/代码变更，解决最严重的痛点

Phase 2 — [structural step]

阶段2——[结构性步骤]

What NOT to do, and why ← the rejected options, each with its reason;

请勿执行的操作及原因 ← 被否决的选项，每个选项附带原因；

prevents the next person from re-proposing them
防止他人在未来重新提出这些选项

Phase 3 (optional) — [riskiest piece] ← last and severable; phases 1–2 must not depend on it

阶段3（可选）——[风险最高的部分] ← 最后执行且可独立拆分；阶段1-2不得依赖此部分

Why this shape and not the alternatives ← one paragraph per losing design

为何选择此方案而非其他备选方案 ← 每个被淘汰的设计方案对应一段说明

Appendix — exact names, gotchas, evidence ← for implementers; plus the evidence folder path

附录——确切名称、陷阱、证据 ← 供实施人员参考；附带证据文件夹路径


3. The advisory is a Markdown document — follow the diagram convention in `${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md`: open with one overview diagram placed before `## The N problems worth fixing…` (typically a `graph TD` of the recommended phases and their key changes), and use `erDiagram` for proposed schema/mapping changes and `flowchart TD` for phase/decision logic.
4. Numbers keep their queries; claims keep their citations; corrections are stated plainly ("field X does not exist — sum the rows instead").
5. If the user maintains a knowledge base, offer to file the advisory there so it compounds.

3. 咨询文档为Markdown格式——遵循`${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md`中的图表规范：在`## 值得修复的N个问题…`之前添加一张概述图（通常为推荐阶段及其关键变更的`graph TD`图），使用`erDiagram`展示拟议的模式/映射变更，使用`flowchart TD`展示阶段/决策逻辑。
4. 数据需附带查询语句；主张需附带引用；修正需明确说明（如「字段X不存在——请改为汇总行数据」）。
5. 若用户维护知识库，主动提出将咨询文档存入其中，以便积累沉淀。

Scaling down

规模缩减

The method survives without the multi-agent machinery — the phase separation is the skill:
  • No Workflow tool: sequential subagent calls (readers → designers → reviewer), same prompts and schemas.
  • No subagents at all: do the phases yourself in strict order — write the study digest to a file before designing; write 2–3 genuinely different designs before judging; then switch to attack mode against the live system. Never let design start before study is written down, or the facts bend to fit the design.
  • Small question (one mapping, one field): a single study pass + a single design + a self-review may suffice — but keep the existence-check and the read-only rule; those are non-negotiable at any scale.
即便没有多Agent机制，此方法依然有效——阶段分离是核心技能：
  • 无工作流工具：按顺序调用子Agent（读取器→设计师→审查者），使用相同的提示词和schema。
  • 无任何子Agent：严格按顺序自行完成各阶段——设计前先将研究摘要写入文件；在评判前撰写2-3个真正不同的设计方案；然后切换至针对实时系统的攻击模式。绝不能在研究摘要写入前开始设计，否则事实会被扭曲以适配设计。
  • 小型问题（单一映射、单一字段）：单次研究+单一设计+自我审查可能足够——但需保留存在性检查和只读规则；这些在任何规模下都是不可协商的。

Red flags

警示信号

ThoughtReality
"The docs say how it works, skip the live check"Docs state conventions; the live system decides. Verify both schema and convention.
"One good design is enough"One design hides its trade-offs. The panel exists to surface them.
"The designs look solid, skip the attack pass"Every run of this method has caught nonexistent fields or broken consumers. Looking solid is the failure mode.
"I'll write to the live system, it's just a test record"A study writes nothing. Ever.
"The digest says it, so it's true"Digest errors propagate to all designs — the reviewer re-verifies primary sources.
"Ship the recommendation without the 'what NOT to do' section"Rejected options without recorded reasons get re-proposed in three months.
想法实际情况
「文档说明了运作方式，跳过实时检查」文档仅说明约定；实时系统才是最终依据。务必同时验证模式和约定。
「一个好的设计方案就足够了」单一设计方案会隐藏其权衡取舍。设计小组的存在就是为了凸显这些取舍。
「设计方案看起来很可靠，跳过攻击校验」此方法每次运行都会捕获不存在的字段或受影响的消费者。看似可靠正是失败模式的表现。
「我会写入实时系统，只是测试记录而已」研究阶段绝不写入任何内容。永远不。
「摘要这么写，所以是对的」摘要错误会传递给所有设计方案——审查者会重新验证原始来源。
「不包含『请勿执行的操作』部分就交付推荐方案」未记录原因的被否决选项会在三个月后被重新提出。

Bundled resources

配套资源

  • references/workflow-template.md
    — a ready-to-adapt Workflow script skeleton (Claude Code) with the three JSON schemas (findings, design, feasibility) and placeholder markers. Read it when you're about to run the pipeline with the Workflow tool.
  • references/workflow-template.md
    —— 可直接适配的Workflow脚本框架（Claude Code），包含三个JSON schema（发现结果、设计方案、可行性）及占位标记。当你准备使用Workflow工具运行此流程时，请查阅此文档。