Project Infrastructure

project-infrastructure

一个用于初始化、审计和维护项目基础设施的 Claude Code skill，确保团队工程实践的一致性。

功能

此 skill 将团队的工程标准转化为可执行的基础设施。只需在 .infrastructure/team.yml 中声明一次标准，skill 即可：

• 脚手架化 — 生成完整的项目结构，包含文档和工具配置
• 审计 — 对照声明的标准检查现有项目，输出差距报告
• 文档生成 — 自动生成架构文档、入职指南、编码规范、踩坑目录
• 标准传播 — 将标准变更同步到多个项目

设计思路

team.yml（声明式配置）
    ↓
skill 自动生成（自动化）
    ↓
文档 + 配置 + 工具（一致性）
    ↓
审计验证（强制约束）
    ↓
团队迭代（持续演进）

安装

方式一：全局 Skill（所有项目可用）

mkdir -p ~/.claude/skills
cp -r project-infrastructure ~/.claude/skills/

方式二：项目级 Skill（仅当前项目）

cp -r project-infrastructure your-project/.claude/skills/

复制后 Claude Code 会自动发现，无需额外注册。

使用方法

在 Claude Code 中

安装后通过自然语言触发，例如：

• "初始化项目基础设施"
• "用团队标准搭建这个仓库"
• "审计这个项目的规范合规性"
• "生成入职文档"
• "我们把单例模式加入禁用列表，更新到踩坑里"

或直接使用斜杠命令：

/project-infrastructure

工作流

1. 初始化新项目

infrastructure init

引导创建 .infrastructure/team.yml，然后生成脚手架：

project/
├── .infrastructure/
│   └── team.yml              ← 团队标准（编辑此文件）
├── docs/
│   ├── README.md             ← 自动生成
│   ├── ARCHITECTURE.md       ← 自动生成
│   ├── ONBOARDING.md         ← 自动生成
│   ├── CODING-STANDARDS.md   ← 自动生成
│   ├── DECISION-LOG.md       ← 自动生成
│   └── PITFALLS.md           ← 自动生成
├── .gitignore                ← 自动生成
├── .editorconfig             ← 自动生成
├── Makefile                  ← 自动生成
└── ...（工具配置文件）

2. 审计现有项目

infrastructure audit

检查命名规范、工具存在性、设计模式、踩坑合规，输出通过/失败/警告报告。

3. 生成文档

infrastructure docs

从 team.yml 重新生成全部文档。文档为完全重新生成 — 编辑 team.yml，而非输出文件。

4. 跨项目更新

infrastructure update

标准变更时，识别受影响的项目文件并制定迁移计划。

核心概念

.infrastructure/team.yml — 单一事实来源

每个文档、配置、检查都从此文件派生。包含 7 个部分：

部分	说明
team	团队标识与联系方式
tech_stack	声明使用的语言、框架、数据库等
conventions	命名、分支、提交、代码风格
design_patterns	推荐和禁用的设计模式
pitfalls	已知的重复性错误
ci_cd	流水线和部署配置
onboarding	新人入职指引

完整配置示例见 examples/team.yml.example。

踩坑系统

这是最强大的功能。每当团队犯错并说"我们应该记住别再做这个"时，添加它：

pitfalls:
  - rule: "禁止创建 goroutine 时不使用 context 取消"
    reason: "超时/取消时 goroutine 泄漏，资源永不释放"
    alternative: "使用 errgroup.Group + context"
    severity: critical
    category: reliability

Skill 会自动：

• 在 docs/PITFALLS.md 中收录
• 在 audit 检查中标记违规
• 在 docs/ONBOARDING.md 中提醒新成员

渐进式披露

Skill 遵循 Claude Code 的三层加载机制：

1. SKILL.md（描述约 150 词）— 始终加载，匹配时触发
2. 参考文件 — 请求具体操作时才加载
3. 脚本和模板 — 执行时使用，不加载到上下文

即使标准不断扩展，skill 始终保持轻量。

迭代策略

工程标准会持续演进，管理变更的方式：

1. 小变更（新坑点、新工具）：编辑 team.yml，运行 infrastructure docs
2. 中变更（版本升级、规范调整）：编辑 team.yml，运行 infrastructure update
3. 大变更（架构转换、新语言）：在 DECISION-LOG.md 中添加 ADR，然后更新 team.yml 并运行 infrastructure update

规则： 永远不要直接编辑生成的文档。始终编辑 team.yml 并重新生成。

文件结构

project-infrastructure/
├── SKILL.md                          # 入口文件（始终在上下文）
├── scripts/
│   ├── scaffold.sh                   # 项目脚手架生成器
│   ├── audit.sh                      # 规范合规检查
│   └── validate-config.sh            # team.yml 格式校验
├── references/
│   ├── config-schema.md              # team.yml 完整字段参考
│   ├── init-workflow.md              # 初始化分步指南
│   ├── audit-workflow.md             # 审计分步指南
│   ├── docs-generation.md            # 文档生成指南
│   └── update-workflow.md            # 跨项目更新指南
├── assets/
│   └── templates/
│       ├── team.yml.template         # 空白 team.yml 模板
│       ├── README.md.template
│       ├── ARCHITECTURE.md.template
│       ├── ONBOARDING.md.template
│       ├── CODING-STANDARDS.md.template
│       ├── DECISION-LOG.md.template
│       └── PITFALLS.md.template
└── examples/
    └── team.yml.example              # 真实配置示例

团队使用建议

1. 从小开始 — 先用 3-5 条踩坑起步。团队在协作中会发现更多。
2. 踩坑要具体 — "不要使用单例" 不如 "不要在数据库连接上使用单例，因为 X" 有用。
3. 定期审查 — 建议每季度审查一次 team.yml，清理过时规则，补充新发现。
4. 分享示例 — 让新团队参考 examples/team.yml.example 作为起点。
5. 使用 ADR — 任何重大标准变更都在 DECISION-LOG.md 中记录决策原因。