骨架决定后面好不好改
新项目开始时随手建几个文件也能跑起来，问题通常出现在半年后：变量到处重复定义、角色只能用于当前环境、没人说得清哪份清单是生产的。骨架的价值是把这些约定提前固定下来——目录位置、变量分层、命名习惯、检查门禁，让项目在扩张时保持可读。
基本信息
| 入口 | 仓库根目录的配置文件与总剧本，固定工作目录执行 |
|---|---|
| 清单与变量 | 按环境分目录，秘密单独加密放置 |
| 角色 | 用官方提供的初始化命令生成标准目录，再按需删减 |
| 依赖 | 用需求文件声明第三方集合与角色版本并锁定 |
| 扩展位 | 自研模块与过滤器的放置目录，避免散落各处 |
| 门禁 | 静态检查与语法检查接入提交前钩子或流水线 |
典型使用场景
- 新项目立项：从骨架起步，避免边写边补结构
- 团队统一：所有人按同一套目录与命名约定协作
- 项目交接：接手者按骨架定位到清单、变量、角色、依赖
- 多环境扩展：新增环境只需复制清单目录并填值
- 自定义扩展：自研模块与过滤器有约定位置，便于复用
- 质量门禁：语法与规范检查在提交前自动执行
起步清单
起步清单
# 1) 建仓库骨架
# ansible.cfg 固定清单路径、并发度、连接参数、日志
# site.yml 总入口：编排角色与顺序
# requirements.yml 集合与角色依赖，带版本
# inventory/
# production/hosts.ini 生产清单
# production/group_vars/all/ 生产变量（明文与密文分开）
# staging/... 预发清单与变量
# roles/ 用官方命令初始化角色目录后按需删减
# library/ filter_plugins/ 自研模块与过滤器
# .gitignore 忽略重试文件、下载的集合、临时产物
# README.md 怎么装依赖、怎么执行、怎么加环境
#
# 2) 初始化一个角色（生成标准子目录）
# ansible-galaxy role init roles/myapp
#
# 3) 装依赖（按需求文件锁定版本）
# ansible-galaxy collection install -r requirements.yml
#
# 4) 首次自检：语法检查 + 静态检查 + 检查模式预演
# ansible-playbook -i inventory/staging site.yml --syntax-check
# ansible-playbook -i inventory/staging site.yml --check --diff骨架要素与作用
| 要素 | 作用 | 缺了会怎样 |
|---|---|---|
| 仓库内配置文件 | 所有人执行行为一致 | 行为随个人环境变化，问题难复现 |
| 总剧本入口 | 一眼看清编排顺序 | 入口分散，执行靠口口相传 |
| 按环境划分的清单 | 环境差异有明确归属 | 参数写进剧本，换环境要改逻辑 |
| 需求文件 | 依赖版本可复现 | 不同时间执行得到不同结果 |
| 扩展目录 | 自研代码有位置 | 模块散落在各处，无法复用 |
| README | 说明如何执行与扩展 | 交接成本高，错误用法反复出现 |
| 检查门禁 | 低级问题提交前拦截 | 错误在运行时才暴露 |
骨架不必一次到位：先保证配置文件、清单目录、角色目录与需求文件四样齐全，其余部分在真正需要时再补。过度设计的前期结构往往与实际需求不匹配，反而更容易被废弃。
不要把下载下来的第三方集合与角色直接提交进仓库：它们应当由需求文件在部署时拉取并按版本锁定。缺版本约束时，某天上游变更会让同一份代码产生不同行为，排查方向会被带偏。
文档该写什么
README 只需要回答四个问题：依赖怎么装、剧本怎么跑（含清单与标签示例）、变量在哪一层改、新增一个环境或角色要动哪些文件。把这份说明写清楚，等于把骨架的约定固化成团队共识。