1. 问题背景团队开始让 AI Coding Agent 处理小任务后最常见的失败点不是“代码不会改”而是环境跑不起来。我遇到过几类典型日志npm test # error: The engine node is incompatible with this module pytest # error: pg_config executable not found npx playwright test # error: Host system is missing dependencies to run browsers docker compose up -d # api connects postgres before postgres is ready这些问题对人来说都能绕切一下 Node 版本、装个系统库、手工起数据库、重新跑一遍测试。但 AI Coding Agent 只能按仓库里的显式配置执行。环境没有写清楚它就会先卡在 setup 阶段。本文给一套可复制的配置思路用 Dev Container 固定语言运行时和系统依赖。用 Docker Compose 固定 Postgres、Redis 等依赖服务。用脚本固定test、lint、dev、migrate入口。用镜像预检提前排掉 pull 阶段的不确定性。2. 推荐目录结构先把环境文件放进仓库而不是放在个人电脑里。. ├── .devcontainer/ │ ├── devcontainer.json │ └── Dockerfile ├── compose.dev.yaml ├── .env.example ├── package.json ├── Makefile └── README.md建议分工文件作用.devcontainer/devcontainer.json定义开发容器、端口、启动后命令.devcontainer/Dockerfile固定语言版本和系统依赖compose.dev.yaml固定数据库、缓存、对象存储等依赖服务.env.example给新环境和 AI agent 明确变量入口package.json/Makefile提供统一任务入口README.md解释背景不承载全部机器步骤README 可以保留说明但机器要执行的步骤要尽量进配置。3. Dev Container 配置最小devcontainer.json{name:ai-ready-dev,build:{dockerfile:Dockerfile},forwardPorts:[3000],postCreateCommand:npm ci,remoteEnv:{NODE_ENV:development},customizations:{vscode:{extensions:[dbaeumer.vscode-eslint]}}}对应 DockerfileFROM docker.1ms.run/node:22-alpine RUN apk add --no-cache \ bash \ curl \ git \ python3 \ make \ g \ libc6-compat WORKDIR /workspace这里解决三件事Node 版本固定不再依赖本机。native module 需要的构建工具提前装好。AI 执行npm ci时环境一致。如果是 Python 项目也可以用类似方式固定FROM docker.1ms.run/python:3.12-slim RUN apt-get update apt-get install -y --no-install-recommends \ build-essential \ libpq-dev \ curl \ git \ rm -rf /var/lib/apt/lists/* WORKDIR /workspace4. Compose 固定依赖服务AI Coding Agent 跑接口测试时最容易踩到数据库和缓存状态不一致。示例compose.dev.yamlservices:app:image:docker.1ms.run/node:22-alpineworking_dir:/workspacevolumes:-.:/workspacecommand:sh-c npm cinpm run devports:-3000:3000env_file:-.env.exampledepends_on:postgres:condition:service_healthyredis:condition:service_healthypostgres:image:docker.1ms.run/postgres:16environment:POSTGRES_USER:appPOSTGRES_PASSWORD:appPOSTGRES_DB:appports:-5432:5432healthcheck:test:[CMD-SHELL,pg_isready -U app]interval:5stimeout:3sretries:20redis:image:docker.1ms.run/redis:7ports:-6379:6379healthcheck:test:[CMD,redis-cli,ping]interval:5stimeout:3sretries:20注意depends_on.condition: service_healthy只能解决“服务还没 ready 就连接”的一部分问题业务代码里仍然要有连接重试。5. 固定 AI 可执行命令不要只给 AI 写“帮我跑一下项目”。建议把命令固定到Makefile或package.json。示例package.json{scripts:{dev:vite --host 0.0.0.0,lint:eslint .,test:vitest run,test:e2e:playwright test,db:migrate:prisma migrate deploy,db:seed:node scripts/seed.js}}示例Makefilesetup: docker compose -f compose.dev.yaml pull docker compose -f compose.dev.yaml up -d npm ci check: npm run lint npm test e2e: npm run test:e2e给 AI Coding Agent 的任务可以写成makesetupmakecheck这样失败时日志能定位在 setup、lint、unit test、E2E 或数据库初始化阶段。6. 镜像预检开发容器和依赖服务通常至少包含这些镜像Node / Python / Go / Java 运行时。Postgres / MySQL / Redis / MinIO。Playwright / Chromium 相关运行时。Nginx / Caddy 等本地代理。建议在 AI 任务开始前做固定 tag 预检dockerpull docker.1ms.run/node:22-alpinedockerpull docker.1ms.run/python:3.12-slimdockerpull docker.1ms.run/postgres:16dockerpull docker.1ms.run/redis:7毫秒镜像1ms.run在这里解决的是镜像入口和拉取稳定性问题。它不是 AI Coding Agent也不能替代测试、review 和权限控制。它适合放在 Dev Container 基础镜像、Compose 服务镜像、CI 预拉镜像这些位置。7. 验证步骤建议按下面顺序验证不要一上来就让 AI 改业务代码dockercompose-fcompose.dev.yaml pulldockercompose-fcompose.dev.yaml up-ddockercompose-fcompose.dev.yamlpsnpmcinpmrun lintnpmtest如果有 Playwrightnpx playwrightinstall--with-depsnpmrun test:e2e如果有数据库迁移npmrun db:migratenpmrun db:seed8. 常见问题排查现象优先检查npm ci失败Node 版本、lockfile、native module 系统依赖pytest缺库Python 镜像、libpq-dev、build-essentialAPI 连不上数据库.env.example、Compose 网络、healthcheckdocker compose up成功但接口 500迁移和 seed 是否执行Playwright 报浏览器依赖浏览器依赖是否进入容器AI 改完代码无法验证test/lint是否有固定入口9. 小结AI Coding Agent 进入团队后开发环境会从“人能凑合”变成“机器必须复现”。实操优先级建议是固定语言版本和系统依赖。固定 Postgres、Redis 等依赖服务。固定测试、lint、迁移命令。固定基础镜像 tag 并提前预检。让 AI 在同一套setup - check - run链路里工作。先让项目跑起来再讨论 AI 改得好不好。