docs: define direct Dev API development loop

README.md

@@ -30,6 +30,7 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube
 - [路线图](docs/roadmap.md)
 - [ADR-0001：采用 Kubernetes API 作为资源模型](docs/decisions/0001-kubernetes-api-machinery.md)
 - [ADR-0002：采用 k0s 与可选工作负载运行时](docs/decisions/0002-k0s-optional-workload-runtime.md)
+- [ADR-0003：直接连接 Dev API 的开发循环](docs/decisions/0003-dev-api-development-loop.md)
 
 ## 当前状态
 

docs/concepts/environments.md

@@ -7,6 +7,11 @@ Dev 使用 managed runtime profile，以单台启用了 worker 的 k0s control n
 API、Flux、Ayatori controllers 和平台 operators。Job 等非控制 workload 应使用外部
 执行后端或后续加入的 execution worker，不与平台控制组件争抢资源。
 
+Dev 是允许随时部署、停止和销毁 workload 的可破坏环境。它不要求所有开发中组件始终
+由 GitOps 管理：Flux 可以只维护稳定基础组件；正在开发的 controller 可以暂停其
+in-cluster deployment，由开发机上的进程直接连接 Dev API。准备集成验证时，再将同一
+组件构建为不可变镜像并恢复完整 GitOps 部署。
+
 首个功能通过 Dev 集成测试后，创建独立 Prod，并从该制品开始执行正式 promotion 流程：
 
 ```text

docs/decisions/0002-k0s-optional-workload-runtime.md

@@ -40,9 +40,9 @@ API-only 描述的是运行拓扑，而不是 API 功能子集。其他组件仍
 API-only 实例测试真实 CRD、admission、watch 和 reconcile 行为，而不必先准备 CNI、
 worker 与完整 GitOps 环境。
 
-API-only 因此可作为可选的 local development profile，但不构成独立的长期环境，也不
+API-only 可以用于隔离的 API 实验、bootstrap 与恢复开发，但不构成独立的长期环境，也
-替代 Dev 集成测试。Flux、in-cluster service discovery、Pod 调度和 executor 集成仍然
+不是日常开发的默认路径。日常开发进程可以直接连接 managed runtime Dev 的 API。Flux、
-必须在 managed runtime Dev 中验证。
+in-cluster service discovery、Pod 调度和 executor 集成仍然必须在 Dev 中验证。
 
 ### Managed runtime
 

docs/decisions/0003-dev-api-development-loop.md

@@ -0,0 +1,87 @@
+# ADR-0003：直接连接 Dev API 的开发循环
+
+- 状态：Accepted
+- 日期：2026-09-17
+
+## 背景
+
+如果每次 controller 代码变更都必须构建镜像、推送 registry、等待集群拉取并 rollout，
+开发反馈会被制品发布流程主导。Ayatori 的开发机与 Dev 位于可互通的内部网络，不需要为
+获得快速反馈而复制一套本地集群。
+
+Dev 本身就是可破坏的集成与实验环境，允许随时部署、停止和删除 workload。完整 GitOps
+是 Prod 的运行要求，也是 Dev 的最终集成验证目标，但不是每一个开发中组件在每一个时刻
+都必须采用的交付方式。
+
+## 决策
+
+日常 controller 开发默认直接连接 Dev API：
+
+```text
+Dev k0s API
+    ↑ kubeconfig / internal network
+developer workstation
+    └── locally built controller process
+```
+
+修改代码后只需重新编译或由 file watcher 重启本地进程。只有进入真实部署集成验证时，
+才构建不可变镜像并交给 Dev GitOps 部署。
+
+API-only profile 仍然保留，但主要用于隔离 API 实验、bootstrap 和恢复开发；它不是为了
+每位开发者复制一个长期 local environment。
+
+## 单写入者约束
+
+本地 controller 接管某类资源前，必须暂停对应的 in-cluster controller。若该 Deployment
+由 Flux 管理，应暂停对应 Flux reconciliation 或使用明确的 Dev deployment mode，避免
+Flux 立即恢复副本数。
+
+本地与 in-cluster controller 使用相同的 leader-election lease 和 identity domain，作为
+防止意外双写的最后一道保护；正常流程仍应先停止集群内实例，而不是依赖抢占 leader。
+
+Dev controller 的凭据只允许操作 Dev API 与 Dev 后端资源，不得拥有 Prod 权限。
+
+## GitOps 范围
+
+Dev 可以只用 GitOps 管理稳定底座：
+
+- k0s 之上的基础 namespace、RBAC 与 policy；
+- Flux 自身；
+- 已稳定的 Ayatori controller/operator；
+- 共享的观测和开发依赖。
+
+活跃开发中的 controller 可以暂不纳入 Flux，或以可暂停的独立 Kustomization 管理。进入
+集成验证时必须恢复以下真实部署路径：
+
+```text
+source commit
+→ immutable image
+→ Dev GitOps deployment
+→ RBAC/network/service/admission integration tests
+```
+
+Prod 只接收经过该路径验证的制品，不运行来自开发机的进程。
+
+## Admission 策略
+
+Ayatori 尽量避免 webhook，降低控制面可用性依赖和本地开发复杂度。校验按以下顺序实现：
+
+1. CRD OpenAPI schema、枚举、范围与结构化默认值；
+2. CEL validation 与 `ValidatingAdmissionPolicy`；
+3. controller reconcile 中依赖后端状态的异步校验，并通过 conditions 报告；
+4. 只有无法由上述方式正确表达的同步校验才使用 validating webhook。
+
+不使用 mutating webhook 隐藏重要默认行为。API version conversion webhook 只在真实版本
+演进需要时引入。
+
+确实需要调试 webhook 时，Dev apiserver 可以通过内部网络直接访问开发机上的 HTTPS
+endpoint；这不要求 controller 镜像先部署进集群。最终证书、Service 和 failure policy
+仍必须在 Dev GitOps 集成阶段验证。
+
+## 结果
+
+- 大多数 reconcile 开发不再经历镜像 push/pull 循环。
+- 所有开发者共享真实 Dev API 和后端边界，减少本地环境漂移。
+- Dev 不保证持续保持完整 GitOps 状态，但必须能够恢复到完整集成形态。
+- 需要明确的暂停、接管和恢复流程，避免本地与集群 controller 双写。
+- webhook 被限制为必要机制，而不是默认扩展方式。