homelab-wiki/AGENTS.md

人与 AI 共用的知识库

先读 README.md，按任务从 services/index.md 和 architecture/constraints.md 查找资料， 并检查 verification.md 中的相关冲突。不要求把整个仓库一次性放入上下文。

• 正式知识写给人和 AI 共同阅读；本文件只放工作规则，不另存一份服务事实。
• 以中文维护正文、commit、PR；配置键、命令和上游专有名称保留原文。
• 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。
• 查询服务或项目状态前先问维护者：哪些工作正在动态进行、由哪个 ticket 跟踪、哪些现状尚未记录。已有明确授权的范围无需重复询问；不能从一个项目扩大到其他项目或现场查询。
• 维护者指定 ticket 为依据时，先读正文和讨论，区分已完成阶段与开放的后续范围。issue open 不等于尚未部署，README 与 ticket 不同也不能立即认定为运行异常。
• 修改前读取对应源码 README/runbook；需要现场核实时先取得维护者对范围的确认。发现差异先记录来源，不能自行把计划升级为事实。
• 新增服务同时补用途、入口、登录方式、第一次使用示例、依赖和故障入口。
• 改变行为、入口、依赖、状态或恢复方法时，在同一任务更新对应文档与服务索引。
• 跨仓库修改互相关联 commit/PR；未完成的文档同步明确记入 verification.md，不能宣称全部完成。
• 架构约束变更必须明确说明旧规则、新规则和原因，不得静默删除约束来迁就实现。
• 每项当前事实注明来源；last_verified 只在完成所述现场验证后更新，不随文字编辑刷新。
• 凭据只记录取得方式和受管位置，不复制实际密码、token、私钥、state 或含敏感值的输出。
• 不复制 apps/tailscale/helm.sh 的内容。迁移旧文档前先审查敏感内容，不能整库直接发布。
• 遵守 CONTRIBUTING.md；不把临时检查日志和个人 agent memory 当成正式文档。