本地开发与 Docker
先记录可复现的本地工作路径，再决定是否用 Docker。对常见 Web/服务项目，“主机运行源码，Compose 运行数据库等依赖”可以作为起点；它不是所有项目的硬性要求。
选择开发模式
| 模式 | 适用情况 | 必须写明 |
|---|---|---|
| 主机源码 + 容器依赖 | 需要快速热更新/调试，同时要统一数据库、缓存或队列 | 主机工具和锁文件、依赖地址、Compose 项目名、端口、数据保留 |
| 全容器开发 | 工具链、系统依赖或团队环境差异需要容器统一 | 开发镜像、挂载和权限、调试/热更新、支持架构 |
| 原生开发 | SDK、CLI、桌面/移动端或研究任务容器收益不大 | 支持的工具链、安装方法、隔离依赖、可验证命令 |
说明操作系统、CPU、Docker Compose 最低能力，以及安装、初始化、配置、启动、健康检查、测试、日志、停止、依赖更新和数据恢复命令。Devcontainer 是可选的编辑器环境，不需要为了它重复维护另一套 Compose。
给人类与 AI 使用的可复现命令
在 README、AGENTS.md 或本页记录受支持的安装、启动、检查和停止命令，并写明工作目录、依赖、配置来源和关键选项。人类与 AI 代理应复用这些已验证命令，不能靠猜测拼接会访问共享环境的命令。默认脚本应可安全重复运行；清空数据、重建共享资源或触达线上服务的操作要单独说明其影响和适用授权。
Compose 文件和隔离
新项目可以把本地状态依赖放在 compose.yaml，完整容器开发另放 compose.full.yaml；可选工具只在配置并维护对应 profile 时加入。生产部署配置不应意外混进本地默认命令。
- 每个独立项目、worktree 和临时测试使用不同的 Compose 项目名，例如 sample-app-dev、sample-app-pr142。
- 不固定 container_name、volume 名或 network 名；让 Compose 按项目隔离。共享资源需要明确所有者、消费者和清理范围。
- 端口可配置且默认只发布到 127.0.0.1。端口隔离与容器/网络/卷隔离是不同问题。
- 集成测试使用自己的测试环境、数据库和端口；禁止从 shell 残留变量意外连到开发、测试或生产数据。
- 受 Codex 等工具管理的 worktree 保持原处，不为 Compose 路径习惯搬动代码。
Compose 默认网络内使用服务 DNS 和容器端口，例如 db:5432；主机进程使用映射到 loopback 的端口。容器中的 localhost 指向容器自己。浏览器使用的公开 URL 与容器内部服务地址、OAuth callback 地址分开配置。
启动和就绪
depends_on 默认只描述启动顺序，不保证数据库已经可用。依赖确实时使用健康检查和 service_healthy；应用客户端仍应实现有上限的超时、重试和重连。健康检查不应偷偷执行迁移或修改业务数据。
使用非 root 应用进程，除非平台或开发工作流有明确限制。不要为方便而挂载 Docker socket、Kubernetes 凭据或开放管理员身份。
配置、密钥和挂载
提交不含秘密的 .env.example，提供安全的可替换样例。解释 Compose 插值、shell 环境、env_file 和容器 environment 的实际优先级；插值文件不会自动注入所有容器。重要设置缺失时给出清楚错误，不要静默切换到线上地址。
本机密钥文件应忽略并限制访问；Docker build 不得把秘密放入 ARG、ENV、镜像层或已复制的 .env。BuildKit secret/SSH mount 用于需要凭据的构建阶段。Compose 文件挂载的 secret 仍然是需要保护的本机文件，不是线上秘密保险库。
只挂载应用需要的源码与配置目录。挂载目录会遮蔽镜像内已有文件；Linux 容器中的 node_modules/venv 应与不兼容的主机依赖分离。依赖卷可能保存旧内容，应有基于锁文件的刷新命令。
数据、停止和重置
普通 stop、down、镜像重建与启动不应删除持久数据。文档说明卷包含什么、谁拥有、备份/导出和初始化方式。删除卷或数据库前要明确具体环境、资源名、数据所有者和用户授权范围。
# 只解析 Compose 配置，不启动容器
docker compose --env-file .env.local -p sample-app-dev -f compose.yaml config --quiet
# 启动本地依赖，并等健康检查
docker compose --env-file .env.local -p sample-app-dev -f compose.yaml up -d --wait
# 查看状态和尾部日志
docker compose --env-file .env.local -p sample-app-dev -f compose.yaml ps
docker compose --env-file .env.local -p sample-app-dev -f compose.yaml logs --tail=100 db cache
# 停止；保留服务和数据资源
docker compose --env-file .env.local -p sample-app-dev -f compose.yaml stop
# 移除该项目的容器/网络；命名卷仍保留
docker compose --env-file .env.local -p sample-app-dev -f compose.yaml down
down --volumes 是独立的数据重置操作，不是日常停止或重建命令。禁止把全局 prune/删除作为常规初始化脚本的一部分。
验证等级
Compose 配置解析只能说明结构和插值有效，不能说明镜像可拉取、应用能启动、热更新正常、数据持久化正确或备份可恢复。分别记录配置检查、镜像/启动测试、跨模式验证和真实恢复演练，不把它们混为一种“Docker 已测试”。
可改编的基础服务与完整应用 Compose 样例见 本地开发模板。