# Architecture Guard

> Use before modifying code that touches module boundaries, AI/Provider SDK calls, or the monorepo layout. Do NOT use for pure content/documentation edits that don't change code structure.

- Skill: `photonics-dhl/architecture-guard` (Agent Skill)
- Install (CLI): `npx skillmds@latest add photonics-dhl/architecture-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/photonics-dhl/architecture-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: photonics-dhl (https://skillmd.com/u/photonics-dhl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/photonics-dhl/architecture-guard

---


# Architecture Guard — 架构边界守卫

改代码前核对模块边界与系统架构约束，防止边界腐蚀。架构事实来源：Spec §14（系统架构）、§9.3（AI 路由）。

## 何时使用 / 何时不使用

- **使用**：新增/移动模块；新增对外部服务（AI 模型、存储、队列）的调用；改变 apps/ 与 packages/ 之间依赖方向；写任何调用模型 Provider 的代码。
- **不使用**：纯文档、文案、样式微调等不触碰模块边界的修改。

## 检查清单

### Monorepo 边界（Spec §14.1）

1. **应用归位**：可运行服务放 `apps/`（web、api、agent-worker、science-worker、sandbox-controller）；可复用领域逻辑放 `packages/`（domain、database、auth、sdf-schema、versioning、storage、ai-gateway、search、ui、config、observability）；基础设施放 `infra/`（compose、nginx、sandbox、scripts、migrations）。
2. **依赖方向**：`apps/` 可依赖 `packages/`，`packages/` 之间按领域分层依赖；禁止 app 之间互相 import 内部实现。
3. **不为目录示例搬动稳定代码**：Spec §14.1 的目录树是参考示例，"具体目录必须在现有代码审计后调整；禁止为了匹配此示例而无理由搬动稳定代码"（Spec §14.1 末段）。调整目录结构前必须先有代码审计结论（配合 repo-map skill）。

### AI 调用边界（Spec §9.3）

4. **统一 AI Gateway**：所有模型调用必须经统一 AI Gateway（packages/ai-gateway）；主模型为 MiniMax-M3，回退/兜底策略在 Gateway 内配置实现，不在业务代码写死。
5. **Provider SDK 不得散落业务代码**：业务代码中不得直接 import 模型 Provider SDK 或直接持有 Provider API Key 调用；发现散落的 SDK 调用必须标记并收口到 Gateway（Spec §9.3）。
6. **长任务异步**：AI 长任务必须异步执行（任务 ID + 进度通道），不得用同步 HTTP 请求硬等（Spec §9.3；API 形态见 §16）。
7. **输出校验**：模型 JSON 输出必须经 Schema 校验，失败时有限重试（Spec §9.3）。

### 通用约束

8. **重大架构决定写 ADR**：每个重大架构决定写入 `docs/adr/`（Spec §20.1-8；本项目 ADR 放 `docs/decisions/`，命名 `ADR-NNN-<主题>.md`，见 AGENTS.md 分类规范）。
9. **修改前列风险**：修改前列出受影响文件和风险（Spec §20.1-5）。