ayatori/AGENTS.md

Agent Notes

• 本仓库是 ddupan.top homelab 的内部基础设施控制平面，不以通用发行版为初期目标。
• 提交、文档和代码注释优先使用中文；公共 API 标识符和代码遵循对应语言惯例。
• 不要重新实现已有成熟后端的核心能力；新增实现前先确认能否通过稳定 API 进行薄适配。
• 在自行设计通用控制循环、资源生命周期、调度、回收或故障恢复机制前，先调查 Kubernetes 核心及成熟开源 controller/operator 的实现；优先复用经过验证的模式，并记录有意偏离的 理由。
• 不要引入统一包装所有能力的 Application CRD；应用应直接组合正交的平台资源。
• 所有 controller 必须考虑幂等、observe、finalizer、conditions、删除策略和恢复行为。
• Ayatori 会联动 Kubernetes API、虚拟化、存储、网络及其他外部控制面；集成测试是功能完成 标准的一部分，不得仅凭 fake client 或 mock 测试宣告 controller、adapter 或生命周期变更完成。
• 测试应按风险分层：纯领域规则使用快速单元测试；API schema、CEL、status subresource、 watch/cache、owner reference 和 reconcile 事件链使用 envtest；需要 scheduler、kubelet、网络、 存储或真实后端行为的路径在 Dev 集群或对应后端环境执行端到端测试。
• fake client 适合穷举状态机和错误分支，但它不会完整执行 API server defaulting、validation、 resourceVersion、garbage collection 或新版 Kubernetes 约束；涉及这些语义时必须增加真实 API server 测试。跨 adapter 的共同契约应使用同一套 contract tests，避免各实现产生语义漂移。
• 集成测试必须覆盖正常路径以及幂等重试、controller 重启、依赖稍后出现、删除/finalizer、 后端结果不确定和并发竞态等恢复路径；无法在当前层测试的部分要明确记录由哪一层验证。
• Secret、token、kubeconfig 及具体生产凭据不得提交到仓库。
• deploy/dev/ 与 deploy/prod/ 使用相同制品；生产版本只通过 promotion 更新。
• 内部专用不构成降低测试、版本、恢复、安全和可审计要求的理由。