domain-first-architecture-delphi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Domain-First Architecture Delphi

领域优先架构Delphi

Overview

概述

Use Delphi to expose one specific structural failure: the code claims domain modeling, but ownership is organized by technical buckets (all tables together, all init together, all debug together).

This skill does not ask “what files are big?” It asks:

What is the canonical path per concept?
Where are alternate paths?
Which alternates are duplicates vs diverged behavior?
What is the minimum replace→wire→delete sequence?

REQUIRED SUB-SKILL:

delphi

使用Delphi来揭示一种特定的结构缺陷：代码声称采用领域建模，但职责却按技术模块（所有表放在一起、所有初始化放在一起、所有调试放在一起）来组织。

此技能不会询问“哪些文件过大？”，而是会问：

每个概念的标准路径是什么？
存在哪些替代路径？
这些替代路径是重复代码还是行为出现差异？
最小的“替换→连接→删除”操作序列是什么？

必备子技能：

delphi

Use This Skill When

何时使用此技能

Use when 2+ are true:

A single file defines many domains (or 1000+ lines with unrelated ownership).
Init logic for multiple domains is fused into one orchestration block.
Adding one domain feature touches 4+ files across 3+ directories.
You see repeated “must match X in Y” comments.
You suspect multiple sources of truth for one concept.
You need ticketable seams, not generic “refactor” advice.

Do not use for style cleanup, naming cleanup, or lint-only reviews.

当满足以下2个及以上条件时使用：

单个文件定义了多个领域（或包含1000+行代码且职责不相关）。
多个领域的初始化逻辑融合到同一个编排块中。
添加一个领域功能需要修改3个以上目录中的4个以上文件。
看到重复的“必须与Y中的X匹配”注释。
怀疑某个概念存在多个事实来源。
需要可转化为工单的重构切入点，而非泛泛的“重构”建议。

请勿将其用于风格清理、命名规范整改或仅基于代码检查的评审。

Required Artifacts (Non-Negotiable)

必备产出物（不可协商）

Every run must produce these artifacts.

每次运行必须生成以下产出物。

1) Concept Inventory

1) 概念清单

Concept	Canonical Path	Alternate Paths Found	Divergence Type	Evidence

Divergence types:

```
DUP_PATH
```
— copy of same logic
```
DIVERGENT_PATH
```
— same concept with behavior drift
```
MULTI_SOURCE
```
— multiple sources of truth
```
LAYER_MISMATCH
```
— ownership split by layer bucket
```
HIDDEN_DAG
```
— init dependency exists but not explicit

概念	标准路径	发现的替代路径	差异类型	证据

差异类型：

```
DUP_PATH
```
—— 相同逻辑的复制
```
DIVERGENT_PATH
```
—— 同一概念但行为出现偏差
```
MULTI_SOURCE
```
—— 多个事实来源
```
LAYER_MISMATCH
```
—— 职责按层级模块划分
```
HIDDEN_DAG
```
—— 存在初始化依赖但未显式声明

2) Architectural Mismatch Matrix

2) 架构不匹配矩阵

Domain	Schema Owner	Init Owner	Runtime Owner	Debug Owner	Files Touched for One Change	Mismatch	Severity

领域	架构所有者	初始化所有者	运行时所有者	调试所有者	单次修改涉及的文件数	不匹配情况	严重程度

3) Init Dependency DAG (with payloads)

3) 初始化依赖DAG（含载荷）

Must include data carried by each edge, not just control flow.

Example:

text

spawn_planets -> planet_entity_ids
planet_entity_ids -> seed_markets
planet_entity_ids -> spawn_npcs

必须包含每个边携带的数据，而不仅仅是控制流。

示例：

text

spawn_planets -> planet_entity_ids
planet_entity_ids -> seed_markets
planet_entity_ids -> spawn_npcs

4) Replace→Wire→Delete Map (per finding)

4) 替换→连接→删除映射（每个发现对应一个）

text

Replace: old_fn_a, old_fn_b
Wire: callers X/Y/Z -> canonical_fn
Delete: old_fn_a, old_fn_b after verification

No map = no actionable finding.

text

Replace: old_fn_a, old_fn_b
Wire: callers X/Y/Z -> canonical_fn
Delete: old_fn_a, old_fn_b after verification

无映射则视为无可行的发现结果。

Process

流程

Phase 0 — RED Baseline (Before Guidance)

阶段0 —— RED基准线（指导前）

Run 3 workers without this skill prompt. Force scenario tasks:

Planet feature change crossing map+zone+market
Ship/module change crossing spawn+tactics+loot
NPC debug command + trace change

Record:

Files touched
Dirs touched
Cross-layer hops
Worker rationalizations (verbatim)

在不使用此技能提示的情况下运行3个工作流。强制执行以下场景任务：

跨越地图+区域+市场的星球功能变更
跨越生成+战术+战利品的飞船/模块变更
NPC调试命令 + 追踪变更

记录：

修改的文件
修改的目录
跨层级跳转次数
工作流的推理过程（原文记录）

Phase 1 — Parallel Delphi Lenses

阶段1 —— 并行Delphi视角

Run 5 workers in parallel using

worker-prompts.md

Domain ownership mismatch
Change-coupling / friction
Init DAG extraction
False-constraint audit (framework myths vs real constraints)
Safe seam extraction

使用

worker-prompts.md

并行运行5个工作流：

领域职责不匹配
变更耦合 / 摩擦点
初始化DAG提取
虚假约束审计（框架误区 vs 实际约束）
安全重构切入点提取

Phase 2 — Synthesis

阶段2 —— 综合分析

Merge findings into the 4 required artifacts. Reject any finding lacking file/symbol evidence.

将发现结果合并到上述4个必备产出物中。拒绝任何缺少文件/符号证据的发现结果。

Phase 3 — Ticketization

阶段3 —— 工单化

Create:

One synthesis ticket
One ticket per P0/P1 finding

Each ticket must contain:

Goal
Exact seam boundary
First move-only step
Acceptance criteria
Verification commands
Dependencies

创建：

1份综合分析工单
每个P0/P1级发现对应1份工单

每份工单必须包含：

目标
明确的重构边界
第一步仅移动代码的操作
验收标准
验证命令
依赖项

Scoring Rules

评分规则

Per finding:

Severity:
```
P0 | P1 | P2
```

Friction score:

files_touched + (dirs_touched * 2) + (cross_layer_hops * 3)

Blast radius:
```
low | medium | high
```
Confidence:
```
high | medium | low
```
Evidence:
```
file + symbol + line range
```

If score or evidence is missing, drop the finding.

每个发现的评分维度：

严重程度：
```
P0 | P1 | P2
```

摩擦分数：

修改文件数 + (修改目录数 * 2) + (跨层级跳转数 * 3)

影响范围：
```
low | medium | high
```
置信度：
```
high | medium | low
```
证据：
```
文件 + 符号 + 行号范围
```

若缺少分数或证据，则舍弃该发现结果。

Guardrails

约束规则

Do not propose “lint rules” as primary solution for semantic duplication.
Do not substitute PR process templates for architectural detection.
Do not open with monolithic rewrites.
Start with move-only splits + re-exports, then extraction, then behavior changes.
Re-run concept inventory after each stage and compare deltas.

Success means alternate paths shrink and divergence labels resolve.

不要将“代码检查规则”作为语义重复问题的主要解决方案。
不要用PR流程模板替代架构问题检测。
不要从整体重写开始。
从仅移动代码的拆分 + 重新导出开始，然后进行代码提取，最后再修改行为。
每个阶段后重新运行概念清单并对比差异。

成功的标志是替代路径减少，差异标签得到解决。