AI 项目初始化规范指南 V3.1
> 位置：项目根目录 / .ai-project-setup.md
> 作用：任何 AI 助手在为本项目生成文件、补全代码或建立工程结构前，必须先阅读本指南。
核心原则
- 本指南为参考蓝本：本指南为参考蓝本，可根据项目，自主决策进行剪裁，但必须有相应的理由和原因。涉及到不同的代码托管平台，不同的技术栈，以及特定公司和项目规范的情况下，需要按需调整。代码托管平台也不局限于Gitee，Github等。
- 行为契约优先于业务逻辑：先建立仓库级控制文件，再写业务代码。
- 最小可行，逐步扩展：只生成当前阶段必需的配置，禁止预置未使用的依赖或规则。
- 跨平台兼容：所有配置文件必须同时考虑 Windows、macOS、Linux 开发环境。
- 不泄露凭证：任何配置文件中不得出现真实密钥、密码、Token、私钥路径。
- 平台原生优先：优先使用代码托管平台（Gitee/GitHub/GitLab）的原生机制，禁止重复造轮子。
- 发布可复现：打包过程必须可复现、可回滚，禁止依赖人工记忆或本地未声明的环境差异。
- 环境感知：同一套配置在不同环境中允许差异化行为，禁止用生产级严格度扼杀开发效率。
项目规模评估与文件裁剪指南
在生成控制文件前，AI 必须先评估项目规模，避免过度设计：
| 规模 | 判定标准 | 必须文件 | 可裁剪文件 |
|---|---|---|---|
| 微型 | 单文件脚本 / 临时工具 / < 200 行 | .gitignore、pyproject.toml（或等效） |
.editorconfig、.pre-commit-config.yaml、CI/CD、启动脚本、.dockerignore |
| 小型 | 单一服务 / 无容器 / 无 CI 需求 | 上述 + .editorconfig、.gitattributes |
CI/CD、.dockerignore、启动脚本（可用 python app.py 直接启动） |
| 中型 | 多模块 / 有部署需求 / 团队协作 | 上述 + .pre-commit-config.yaml、启动脚本、CI/CD |
.dockerignore（若无容器化） |
| 大型 | 微服务 / 多前端 / 复杂部署 | 全部 8 项 | 不可裁剪 |
裁剪原则：被裁剪的文件必须在回复中明确说明理由，并标注"当项目规模达到 X 时建议补全"。
根目录行为控制文件清单
以下 8 个文件按优先级排序。AI 必须根据"项目规模评估"决定生成哪些，而非无条件全部生成。
1. .gitignore
作用 ：控制版本库中不跟踪的文件。
必须包含：
- 运行时生成的缓存/编译产物
- 本地环境配置文件（含密钥、数据库连接串）
- 虚拟环境目录
- 操作系统垃圾文件
- 日志与临时文件
- 构建/打包输出目录
- 本地平台配置目录 ：
.gitee/（仅排除本地 IDE 自动生成的 Gitee 配置，不排斥通过 Web 界面配置的仓库级模板） - 子模块状态文件 ：
.gitmodules（若使用 submodule，确保路径与 URL 正确映射）
禁止 ：将.env、密钥文件、本地数据库、个人草稿放入版本库。
2. .gitattributes
作用 ：统一跨平台的文件元数据行为。
必须包含：
- 全局行尾符策略（推荐
* text=auto eol=lf） - 二进制文件标记（图片、压缩包、字体等）
- 合并策略标记（如
CHANGELOG.md merge=union）
禁止 ：让 Windows 开发者提交CRLF导致 diff 噪音。
3. .editorconfig
作用 ：跨编辑器/IDE 统一基础代码格式。
必须包含：
- 字符集（推荐 UTF-8）
- 换行符（推荐 LF）
- 缩进风格与尺寸（按语言区分，如代码 4 空格、配置 2 空格）
- 文件末尾空行、行尾空格修剪
禁止：假设开发者使用特定 IDE，配置必须编辑器无关。
4. pyproject.toml（或对应生态的配置中枢）
作用 ：项目级工具配置的单一事实来源。
必须包含：
- 构建系统声明
- 最低语言版本要求
- 核心依赖范围（不锁定精确版本，留给 lock 文件）
- 代码质量工具参数（格式化、检查、测试）
禁止：将敏感配置、环境相关路径硬编码进此文件。
5. .dockerignore（仅当项目涉及容器化时生成）
作用 ：控制 Docker 构建上下文的边界。
必须包含：
- 版本库目录（
.git） - 本地环境文件
- 虚拟环境
- 测试数据与日志
- 构建产物
- CI/CD 产物目录 （如 Gitee CI 的构建缓存、GitHub Actions 的 artifact 目录）
禁止：将不必要的上下文传入镜像层，导致镜像膨胀或密钥泄露。
6. .pre-commit-config.yaml（仅当项目有团队协作或质量门禁需求时生成）
作用 ：在代码进入版本库前自动拦截格式与基础错误。
必须包含：
- 行尾符/空格修复
- 代码格式化工具
- 静态检查工具
- 密钥扫描工具（如
detect-private-key）
禁止：配置过于繁重导致提交耗时过长；优先本地可运行，不依赖外部网络。
7. CI/CD 流水线配置（按平台选择，仅当项目有自动部署需求时生成）
作用：在远程推送/合并时自动执行质量门禁与部署。
| 平台 | 文件 | 必须包含 |
|---|---|---|
| Gitee | .gitee-ci.yml |
触发条件（push/PR）、依赖安装、代码检查、测试执行、构建/部署步骤 |
| GitHub | .github/workflows/*.yml |
同上 |
| GitLab | .gitlab-ci.yml |
同上 |
通用要求：
- 流水线必须读取项目根目录的配置文件（如
pyproject.toml、.pre-commit-config.yaml），保持本地与远程检查逻辑一致 - 敏感信息（部署密钥、API Token）必须通过平台提供的密钥管理/变量服务注入，禁止写死在 CI 文件中
- 构建产物（如 Docker 镜像）应关联仓库版本标签，禁止使用
latest作为唯一标识
Gitee 特别警示：Gitee CI 的免费额度、并发限制、镜像缓存策略与 GitHub Actions 存在差异，复杂工作流（如矩阵构建、多阶段缓存）可能需要降级设计，禁止直接照搬 GitHub Actions 的复杂模式。
8. 启动脚本（仅当项目需要生产级部署时生成）
作用：统一生产环境的启动入口，消除"靠人记命令"的风险。
单一事实来源原则 ：禁止同时维护 start.sh 与 start.ps1 两份独立脚本。推荐方案：
- 首选 ：使用 Python 跨平台启动脚本（
start.py），内部调用subprocess启动目标进程，Windows 与 Linux 共用同一份逻辑 - 次选：若必须用 Shell，要求两份脚本基于同一份模板生成，并在文件头部标注"本文件由 X 模板自动生成，手动修改时请同步另一平台版本"
必须包含：
- 明确的环境变量加载逻辑（优先外部注入，其次
.env文件） - 明确的进程启动命令（如 Gunicorn/uWSGI/uvicorn 等，按技术栈选择）
- 错误退出码（启动失败时非零退出，便于 CI/CD 和容器健康检查捕获）
- 健壮性要求 ：
- 启动失败时必须输出结构化错误日志（包含失败步骤、环境变量加载状态、依赖检查结论），而非静默退出
- 脚本应包含前置检查（如端口占用、必要环境变量缺失、数据库连通性），任一检查失败立即终止并返回非零退出码
- 禁止在启动脚本中使用
set +e或类似"忽略错误继续执行"的语法
- 跨平台考虑 ：Windows 环境提供
.ps1或start.py，Linux/macOS 提供.sh或start.py，禁止混用 Bash 语法在 PowerShell 中直接运行
禁止：在启动脚本中硬编码密钥、数据库密码或绝对路径；禁止将数据库迁移自动嵌入启动流程。
发布与打包规范
> 本章节确保项目在生产环境中的发布具备一致性、可复现性和回滚能力。
一、打包策略：按场景选择
| 项目类型 | 推荐策略 | 说明 |
|---|---|---|
| 后端服务 / API / 中小型项目 | 全量打包 | 确保每次发布的稳定性和可复现性 |
| 前端大型 SPA / 多模块单体 | 分层构建 | 前端资源通过 CDN 分离，后端仅打包 API 层；禁止将 node_modules 或编译产物全量打入部署包 |
| 微服务仓库 | 模块独立打包 | 每个服务独立打包，禁止全仓库统一大包 |
- 增量打包仅在具备完善的版本差异追踪机制且经评估确认安全时方可使用。
二、打包边界清单
| 类别 | 必须包含 | 必须排除 |
|---|---|---|
| 源码 | 应用源码、配置模板 | .git/、.github/、.gitee/（本地配置） |
| 依赖 | 锁文件（uv.lock / poetry.lock / package-lock.json）及安装清单 |
node_modules/、.venv/、__pycache__/ |
| 资源 | static/、templates/、国际化资源 |
开发期草稿、个人笔记 |
| 数据 | migrations/（迁移脚本独立打包） |
本地数据库文件（*.db、*.sqlite）、测试数据 |
| 配置 | 配置模板（如 .env.example）、部署说明 |
.env、密钥文件、本地覆盖配置 |
| 产物 | 构建输出（若前端已编译） | .pytest_cache/、logs/、temp/ |
三、依赖版本锁定
- 所有运行时依赖必须提供精确版本锁定文件 （如
uv.lock、poetry.lock、requirements.txt含明确版本号）。 - 禁止在发布包中使用通配版本或未经锁定的依赖声明。
四、启动入口一致性
- 统一指定应用入口文件（如 Python 的
app.py/wsgi.py，Node.js 的server.js）。 - 启动脚本（第 8 项文件）必须准确引用该入口，禁止依赖人工记忆切换启动方式。
五、数据库迁移独立执行
- 数据库迁移脚本必须作为独立步骤执行，禁止嵌入应用启动流程。
- 迁移前应具备备份或回滚预案，避免启动时自动执行不可逆 schema 变更。
六、静态资源路径校验
- 打包过程中验证
static/、templates/等目录的相对路径在目标环境中仍然有效。 - 禁止假设源码目录的绝对路径在部署服务器上保持一致。
七、版本化与回滚支持
- 每次发布的包名必须包含版本号与日期 （如
app-v1.2.3-20260425.tar.gz）。 - 保留至少一个历史版本，确保紧急回滚时可直接切换。
- 附带
CHANGELOG或变更摘要，确保发布内容可追踪。 - CHANGELOG 格式 ：遵循 Keep a Changelog 规范，必须包含
Added、Changed、Deprecated、Removed、Fixed、Security六类标签，禁止自由发挥格式。
八、干净环境验证（冒烟检查）
- 发布前必须在全新环境 （如临时容器、干净虚拟机）中执行以下验证：
- 从零解压发布包
- 按文档安装依赖
- 按启动脚本启动应用
- 执行基础健康检查（如首页可达、核心 API 返回 200）
- 验证失败时禁止推进到生产部署。
九、部署配套要求
- 独立目录部署 ：新版本部署到独立目录（如
/opt/app/v1.2.3/），禁止直接覆盖旧版本目录。 - 数据独立挂载 ：日志文件、用户上传文件、运行时配置文件应挂载在版本目录之外（如
/var/log/、/data/uploads/）。 - 原子切换：使用软链接（symlink）或负载均衡权重切换完成版本更替，确保回滚可在秒级完成。
- 临时文件归集 ：运行时产生的临时文件统一进入
temp/或系统标准临时目录，禁止散落在版本目录内（参见 S03 临时文件管理规则）。
平台集成约束（Gitee 场景补充）
若项目托管于 Gitee，除上述文件外，AI 还需检查：
- Gitee Pages / Webhook 配置 ：若启用静态页面或自动化通知，相关配置应放在
.gitee/目录下，且该目录必须被.gitignore排除（避免本地与远程配置冲突）。 - Issue / PR 模板 ：若需要，通过 Gitee Web 界面配置仓库级模板；若通过 Git 跟踪模板文件，应放在
.gitee/中且不被.gitignore排除 ，此时需在文档中明确说明"此.gitee/为仓库级模板，非本地 IDE 配置"。 - 子模块管理 ：若项目依赖其他 Gitee 仓库作为子模块，
.gitmodules中的 URL 必须使用 HTTPS 或 SSH 协议，并确保团队成员有对应访问权限。 - 合并策略：建议开启"禁止强制推送"与"合并前必须通过 CI"选项，在提示词中声明此推荐，但不强制生成平台侧配置。
通用工程约束（适用于所有文件生成）
| 约束项 | 要求 |
|---|---|
| 敏感信息隔离 | 所有凭证、密钥、本地路径必须通过环境变量或外部密钥管理服务注入，禁止写死在任何配置文件中。 |
| 环境分层 | 至少区分 development / production / test 三层，通过文件命名或环境变量切换，禁止在同一份配置中混写多环境参数。 |
| 环境感知降级 | development 模式下，Schema 校验失败可输出警告并降级到默认值（便于调试）；production 模式下严格执行"失败即崩溃"。禁止在开发阶段用生产级严格度打断调试流。 |
| 临时文件归集 | 运行时产生的临时文件必须统一进入 temp/ 或系统标准临时目录，禁止散落在项目根目录或业务代码目录。 |
| 自解释命名 | 文件名、变量名、配置键名必须优先表达意图，减少依赖注释。 |
| 失败即崩溃 | 配置文件在加载时必须经过 Schema 校验，校验失败立即终止启动，禁止静默回退到默认值。（此约束在 development 模式下可被"环境感知降级"覆盖） |
| 本地与远程一致 | .pre-commit-config.yaml 的检查项必须与 CI/CD 流水线的检查项保持逻辑一致，避免"本地通过、远程失败"的断层。 |
| 发布可复现 | 同一份源码 + 同一份锁文件 + 同一套启动脚本，在任何干净环境中必须产生一致的运行结果。 |
| 单一事实来源 | 同一逻辑禁止在多个平台/文件中重复维护；若必须多平台适配，必须基于同一份模板生成，并标注同步关系。 |
AI 执行检查清单
在为本项目生成任何新文件或修改现有文件前，AI 必须自检：
- 是否已完成"项目规模评估"？生成的文件数量是否与规模匹配？
- 是否已检查必备文件的存在性？缺失的需优先补全。
- 新生成的配置是否遵循"最小可行"原则？是否有过度设计？
- 是否遗漏了敏感信息过滤？
- 是否考虑了跨平台兼容性？
- 是否已为配置文件添加了足够的行内注释（说明用途与可调项）？
- 若涉及 Gitee ：是否已区分"本地
.gitee/"与"仓库级模板"的忽略策略？CI 文件是否使用了平台变量而非硬编码密钥？ - 若涉及 Docker ：
.dockerignore是否与.gitignore保持同步，避免构建上下文泄漏？ - 若涉及发布：是否已提供版本化命名、干净环境验证步骤、独立目录部署方案？
- 若涉及启动脚本：是否遵循"单一事实来源"？是否包含前置检查与结构化错误日志？
- CHANGELOG 格式：是否遵循 Keep a Changelog 规范？
备注
- 本指南不绑定具体技术栈，但要求 AI 根据项目实际生态选择对应配置格式（如 Node.js 项目用
package.json替代pyproject.toml，Go 项目用go.mod等）。 - 若项目为纯前端/纯后端/纯脚本，可酌情删减容器化或提交钩子相关文件，但必须在回复中说明删减理由。
- Gitee CI 与本地 pre-commit 的关系：本地钩子负责"快速反馈"（格式、密钥扫描），Gitee CI 负责"完整门禁"（全量测试、构建、部署），两者互补而非替代。
- 启动脚本与打包的关系：启动脚本是发布包的一部分，但必须在干净环境验证阶段独立测试其正确性，禁止假设目标服务器已预装特定全局依赖。
- 规模裁剪不是妥协：微型项目只保留 2 个文件不是"不规范"，而是"不过度"。规范的核心是"恰到好处"，而非"越多越好"。