架构审查 Prompt：分层与依赖审计模板

架构审查 Prompt——分层违规、依赖环、边界泄漏、数据流、跨服务边界，每个维度独立模板，要求 file:line 证据。

发布于: 2026/05/18 作者: AI Productivity Guide Team 🌐 查看英文版本

“帮我审查一下架构”只会得到教科书式模式，对不上你的代码。好的架构审查 Prompt 必须先点名维度（分层、依赖、边界、数据流），强制要求 file:line 证据，并禁止在审查中顺便重写。下面 15 个模板各打一个结构性角度。

适合哪些场景

准备做重构前盘家底的技术负责人、审 junior 团队设计的 staff 工程师、做尽调的创业团队、接手陌生代码库的资深工程师。

什么时候不建议这样写 Prompt

绿地新设计别用——用设计文档 Prompt。200 行以内的小脚本也别用，“架构”就一个文件。

Prompt 结构公式

每个架构审查 Prompt 都要带这六个要素：

角色：让 AI 扮演谁（架构师 / SRE / QA Lead / Release Captain）。
上下文：仓库 / 框架 / 运行时版本 / 涉及哪些文件或 diff。
目标：一个具体可交付物——review 笔记、计划、checklist、测试文件、交接文档。
限制：AI 不能做什么（别重写、别自动 format、别瞎猜版本号）。
输出格式：编号清单、markdown 表格、JSON、unified diff、可直接运行的代码。
示例 / 信号：1-2 条”好输出”示例，或者说明什么是糟糕输出。

这套 Prompt 适合用在哪

重构前的结构评估
接手陌生代码库的入职审查
架构决策记录（ADR）补写
季度技术债 review
尽调和并购评估

15 个可直接复制的 Prompt 模板

1. 分层违规猎杀

第一个跑——大多数架构腐烂从这里开始。

You are a staff engineer reviewing this codebase for LAYERING violations only. Identify imports that cross layers in the wrong direction (UI importing infrastructure, domain importing framework, etc.). For each: file:line, the violating import, the layer rule it breaks, and a one-line refactor sketch. Do not propose rewrites. Return a markdown table with severity (Critical / High / Med).

可替换变量： 仓库文件（Claude Code 自动读）；对话工具需手动粘贴包/模块树

优化建议： 追加：“If layers are not explicit, first infer the intended layer model from folder names, then judge violations against that inferred model.”

2. 依赖环检测

Scan this repo for circular dependencies between modules / packages. Output: (1) cycle as `A -> B -> C -> A`, (2) the import that creates each edge (file:line), (3) which edge is the cheapest to break, (4) one-line break strategy (interface, event, move type). Ignore intra-file cycles.

3. 模块边界泄漏审计

Audit MODULE BOUNDARIES. For each top-level module, list: (1) what types it exports (public API), (2) types that leak through but are internal (e.g., DB rows surfacing in HTTP handlers), (3) internal types reached via deep imports `module/internal/...`. Flag every boundary leak with file:line.

4. 上帝模块 / 中枢模块检测

Find HUB modules: any module with > 5 incoming imports OR > 10 outgoing imports. For each: list the fan-in/out count, the responsibilities tangled inside, and propose a split into 2-3 cohesive submodules. Do not write the refactor — only the split plan.

5. 数据流意外审计

Trace DATA FLOW for the 3 most important entities (infer from naming if not told). For each: (1) where it is created, (2) where it is mutated, (3) where it is read across module boundaries. Flag any "surprise mutation" — state changing in a module that the entity doesn't belong to.

可替换变量： 实体名称（可选——模型可推断）

6. 六边形 / ports-and-adapters 检查

Evaluate this codebase against ports-and-adapters: (1) Is domain logic isolated from frameworks? Cite evidence, (2) Are external systems (DB, queue, HTTP) reached through interfaces or directly? List each direct call (file:line), (3) Where would mocking be hard right now? Rate adherence 1-5 with rationale.

7. 限界上下文漂移审计

Identify implicit bounded contexts in this codebase (group modules by entities they share). Then: (1) Which contexts share the same entity but disagree on its shape? (file:line for each), (2) Which contexts secretly depend on each other through shared mutable state? (3) Suggest one context boundary to make explicit first.

8. 横切关注点泄漏

Audit cross-cutting concerns: logging, auth, telemetry, feature flags, error handling. For each: (1) Is it implemented centrally or sprinkled? (2) List 5 sites where the concern is reimplemented inline, (3) Suggest one extraction strategy (decorator, middleware, hook). Do not perform the extraction.

9. 共享内核风险审计

Identify the "shared kernel" — code imported by > 3 modules. For each shared item: (1) Why does it need to be shared? (2) Is the shape stable, or does it change every sprint? (3) Score coupling risk (Low / Med / High). Flag shared kernel items that are actually leaky abstractions.

10. 异步 / 同步边界审计

Map ASYNC vs SYNC boundaries. Find: (1) sync code that blocks on async (sync over async) — file:line, (2) async code that swallows promise rejection, (3) "fire and forget" calls without retry / dead-letter, (4) mixed paradigms in the same call chain. Output: severity-ranked table.

11. 配置架构审计

Audit how CONFIG flows: (1) Where are env vars read? Centralized or scattered? List read sites, (2) Are defaults / fallbacks documented? (3) Is there a single typed config object, or is `process.env.X` reached directly? (4) Suggest a config-loading pattern for this stack.

12. 插件 / 扩展面审计

If this codebase exposes a plugin or extension surface, audit: (1) What contract do extensions implement? (2) What internals are accidentally reachable? (3) How is versioning handled? If no extension surface exists, say so — do not invent one.

13. 读 / 写不对称审计（CQRS lite）

For the 3 most-used entities, separate READ paths from WRITE paths. Find: (1) Reads that pull through write models unnecessarily, (2) Writes that bypass invariant enforcement, (3) Queries that join 4+ tables (candidates for read models). Suggest one read/write split worth doing first.

14. 多服务边界审计

monorepo 里多个部署单元时用。

This monorepo contains {services}. Audit the SERVICE boundaries: (1) Which packages are imported across service lines? (2) Where do contract types diverge between services? (3) Is there shared DB access (anti-pattern)? (4) Suggest one boundary to harden first.

可替换变量： services —— 例如 “web (Next.js), api (FastAPI), worker (Go)“

15. 架构发现 → ADR 补写

最后跑——把发现转成决策记录。

Take the architecture findings from previous prompts. For each significant decision implied (or contradicted) by the code, draft a short ADR: Title, Status (Accepted / Proposed / Deprecated), Context (2 sentences), Decision (1 sentence), Consequences (3 bullets). Output 5 ADRs maximum, ranked by impact.

容易踩的坑

“帮我审一下架构”——不点名维度，输出全是教科书。
审查中让 AI 顺便重写——诊断清晰度立刻丢失。
不要 file:line 证据——所有发现都无法验证。
从标题猜分层而不是看 import——要按真实依赖图判断。
一次 prompt 跑整个仓库——上下文被稀释，发现互相模糊。
把 AI 输出当终稿——至少人工走查 Top 3 发现一遍。
不做 ADR 补写——发现变成没人执行的只读文档。

优化技巧

每个架构维度单独开线程——分层 / 环 / 边界 / 数据流。
每条发现都要 file:line 证据，要求一加，幻觉就消失。
在 prompt 里加 severity 枚举（Critical / High / Med / Low），强制排序。
让 AI 先从目录推断意图分层模型，再判违规，记得把推断模型写进 ADR。
monorepo 按 service-pair 跑边界审计，别一次全局跑。
把架构审查保存成 /docs/architecture/audits/2026-05-19.md，下次能 diff。
每次审查都配模板 15（ADR 补写）——不然发现会腐烂。

FAQ

每个 PR 都跑架构审查？: 不要——噪音太大。重构前 / 接手代码 / 季度跑即可。diff 用 PR review Prompt。
我的代码库没有显式分层？: 让 AI 先从目录名推断意图分层模型，再判违规。把推断模型写成 ADR。
AI 会幻觉出依赖环吗？: 会。每条边都要求 file:line 的具体 import——给不出就是假的。
和全仓审查有啥区别？: 全仓审查多维度浅扫（安全、依赖、测试）。架构审查只深挖结构性问题。
能跑跨仓库的微服务吗？: 能——粘服务接口定义和消息合约。模板 14 需要两端都有材料才好用。
一次要多久？: 3 万行仓库：每个维度 20-40 分钟，triage + ADR 补写 1-2 小时。