wesleyosantos91-engineering-kit

<div align="center"> # 🧰 工程工具包 **我的可重复使用的工程工具包** — 技能、代理、命令、钩子、DevContainer、多语言、质量门控、MCP 和脚本 — 被 **任何项目** 作为 **git 子模块** 消费，具有 **单一源** 以便一次性更新所有内容。 <br/> [](LICENSE) [](#-quickstart) [](#o-que-vem-no-kit-kit) [](https://github.com/wesleyosantos91) **DevContainer 工具链**           **负载测试 & AI**        </div> > **停止每次从头开始配置环境。** 只需添加工具包一次并保持 **单一源**：当工具包升级时，所有使用它的仓库都会通过 **一个命令** 更新，而无需复制任何内容。 独立且自给自足的项目（不依赖于任何其他仓库）。范围仅限于 **配置**：AI 套件 + 多语言 DevContainer + 工具 — **无** 应用代码。 ## ✨ 亮点 - 🔗 **通过 git 子模块消费** — `bootstrap.sh` 将项目根目录填充为符号链接；更新只需 `git submodule update --remote`。 - 🧰 **多语言 DevContainer** — Java/Maven/Gradle、Python、Go、Rust、Terraform、AWS CLI、Node、Docker-in-Docker 均已准备就绪，可用于学习、POC 和开发。 - 🤖 **AI 套件** — 适用于 **Claude Code 和 Codex** 的代理、技能、命令和钩子，均已注册 MCP。 - ⚡ **令牌保护者** — 为 Claude **和** Codex 初始化了 RTK 和 Caveman。 - ✅ **Java 25 质量门控** — Spotless、Checkstyle、JaCoCo、PIT、ArchUnit（可选）。 - 📐 **规范驱动** — PRD → OpenSpec → SDD → TDD 工作流程。 - 🧪 **负载测试** — k6 和 JMeter。 ## 📑 目录 - [亮点](#-destaques) - [多语言 DevContainer](#-devcontainer-poliglota) - [工作原理（“单一源”）](#-como-funciona-a-fonte-única) - [快速入门](#-quickstart) - [更新工具包](#-atualizar-o-kit-puxar-a-evolução) - [脚本](#-scripts) - [工具包内容](#o-que-vem-no-kit-kit) - [详细文档](#-documentação-detalhada) - [贡献](#-contribuindo) - [许可证](#-licença) ## 🧰 多语言 DevContainer DevContainer 已经启动了日常工具链 — 准备好学习、进行 POC 和开发： | 工具链 | 默认配置 | |---|---| | **Java 25** (Temurin) + **Maven** + **Gradle** | DevContainer 功能 | | **Python 3.12** + `uv` | 功能 + `install-tools.sh` | | **Go** | DevContainer 功能 | | **Rust** (cargo/rustup) | DevContainer 功能 | | **Terraform** | DevContainer 功能 | | **AWS CLI** | DevContainer 功能 | | **JMeter** | `install-tools.sh`（Apache JMeter） | | **k6** | `install-tools.sh`（负载测试；内置 Web 仪表盘，无需 Grafana） | | Node 22、Docker-in-Docker | DevContainer 功能 | | Claude Code、Codex、RTK、OpenSpec、Repomix + MCP | `install-tools.sh`（RTK/OpenSpec 已初始化） | | **Caveman** (+ `caveman-review`) | `install-tools.sh`（令牌保护者，已安装并初始化） | --- ## 🔌 工作原理（“单一源”） ```mermaid flowchart LR kit["工程工具包<br/>(子模块)"] -->|符号链接| root[".claude / .codex / .agents<br/>脚本 / .mcp.json / ... 在根目录"] kit -->|脚手架 + 占位符| proj["CLAUDE.md / AGENTS.md<br/>devcontainer.json"] upd["git submodule update --remote"] -->|工具包的新提交| kit root -.->|立即反映| tools["Claude Code · Codex · 技能 · 钩子"] ``` 秘密在于 **符号链接**： - 所有 **稳定** 的内容（技能、代理、命令、钩子、脚本、DevContainer、质量配置）都从子模块 **符号链接** 到项目根目录。 → 更新工具包？`git submodule update --remote`，符号链接 **已经指向** 新内容。 **您无需复制任何内容**。 - 需要按项目定制的文件很少（`CLAUDE.md`、`AGENTS.md`、`.ai/harness.yaml`、`.devcontainer/devcontainer.json`、`config/pom-quality-plugins.example.xml`） — **复制并定制**（替换 `__BASE_PACKAGE__` / `__PROJECT_NAME__`) — 可由您编辑。 更多详细信息和完整表格参见 [`docs/architecture.md`](docs/architecture.md)。 --- ## 🚀 快速入门 ```bash # 1. 添加工具包作为子模块 git submodule add https://github.com/wesleyosantos91/wesleyosantos91-engineering-kit .engineering-kit git config -f .gitmodules submodule..engineering-kit.branch main # 跟踪 main 分支 # 2. 填充项目根目录 bash .engineering-kit/bootstrap.sh # 3. 版本控制 git add -A && git commit -m "chore: 添加工程工具包" ``` `bootstrap.sh`（在子模块内）**填充** 项目根目录：`.claude/`、`.codex/`、`.agents/`、`.ai/`、`scripts/`、`.mcp.json` 变成根目录的 **符号链接**；`CLAUDE.md`、`AGENTS.md`、`.ai/harness.yaml`、`.devcontainer/devcontainer.json` 被 **定制**（**自动检测** 您的 `src/main/java` 的基准包）。 现在 **在 DevContainer 中打开** （*在容器中重新打开* → 配置 `.engineering-kit/kit/.devcontainer/devcontainer.json`）。 **相同的 `bootstrap.sh`** 在 `postCreate` 中运行，并且由于它 **在容器内**，因此 **安装工具链和 CLI** （Java/Maven/Gradle/Python/Go/Rust/Terraform/AWS/JMeter/k6 + Claude Code、Codex、RTK、OpenSpec、Repomix、Caveman）并 **注册 MCP**。 > 您甚至可以跳过第 2 步：如果您只执行 `git submodule add` 然后启动 DevContainer，`postCreate` 将运行 `bootstrap.sh` 并填充根目录 **和** 安装工具链。执行第 2 步只是为了 **提前看到/提交** 根目录的文件，而无需容器。 ### 克隆所有内容 第一次启动后，符号链接（包括 `.devcontainer/`）被版本控制，因此任何克隆带有子模块的项目 **都会启动所有内容**: ```bash git clone --recurse-submodules https://github.com/voce/seu-projeto.git # 在 VS Code 中打开 -> "在容器中重新打开" ``` > 如果您没有使用 `--recurse-submodules` 克隆？`git submodule update --init --recursive` 然后重新打开容器。对于 Windows 上没有 Developer Mode 的情况，请参见 [`docs/windows.md`](docs/windows.md)。 详细步骤：[`docs/getting-started.md`](docs/getting-started.md)。 > **Windows:** 符号链接需要 **Developer Mode** （或在 DevContainer 内运行 `install.sh`，它是 Linux）。请参阅 [`docs/windows.md`](docs/windows.md)。 --- ## 🔄 更新工具包（拉取更新） ```bash # 在消费项目中 bash .engineering-kit/update.sh # = git submodule update --remote + 重新检查符号链接 git add .engineering-kit && git commit -m "chore: 更新工程工具包" ``` 符号链接配置文件立即反映新内容。`install.sh` 仅在 **新项目** 被工具包提供时重新执行。更多信息请参见 [`docs/updating.md`](docs/updating.md)。 --- ## 🧩 脚本 | 脚本 | 功能 | |---|---| | `install.sh` | 创建符号链接并定制项目特定的文件到目标仓库。标志： `--base-package`, `--name`, `--force`, `--target`. | | `update.sh` | `git submodule update --remote --merge` + 重新检查新符号链接。 | | `uninstall.sh` | 删除符号链接和 `.gitignore` 块。 `--purge-copies` 还删除复制的文件。 | --- ## 工具包内容 (`kit/`) | 路径 | 内容 | |---|---| | `.claude/` | 代理、命令、**技能** （包括 `prd-produto`）、 `settings.example.json` | | `.codex/` | 代理、技能、 `config.example.toml`、MCP 配置文件 | | `.agents/` | Codex 的技能（技能镜像） | | `.ai/` | 规则、提示、引用、模板、 `harness.yaml` | | `.devcontainer/` | 多语言 DevContainer（Java/Python/Go/Rust/Terraform/AWS/JMeter）+ `install-tools.sh` （CLI 和 MCP） | | `scripts/` | `ai/`、`quality/`、 **`hooks/`** 、 `lib/`、`mcp/` | | `config/` | Checkstyle（Java 25）、Spotless、ArchUnit、PIT、POM 插件 | | `docs/ai-harness/` | AI 套件文档（代理、技能、MCP、质量门控、OpenSpec/SDD） | | `.mcp.json`、`openspec/config.yaml`、`compose.yaml`、`infra/localstack/` | MCP、OpenSpec、LocalStack 实验室 | ### **不包含** （故意） - 应用代码 (`src/`、`pom.xml`、`mvnw`）— 每个项目都有自己的代码。 - 本地/生成的状态： `.ai/reports/*`、`.claude/settings.local.json`、`.codex/config.toml`、`**/.terraform/`。 - 任何秘密。令牌/凭证始终来自环境变量（`.env`，从不提交）。 --- ## 演进工具包 编辑 `kit/` 中的有效载荷并在提交前运行验证器： ```bash cd kit bash scripts/ai/validate-skills.sh bash scripts/ai/validate-claude-agents.sh bash scripts/ai/validate-codex-agents.sh ``` 使用工具包的项目通过 `bash .engineering-kit/update.sh` 拉取更新。 --- ## 📚 详细文档 [`docs/`](docs/) 中的逐步指南： | 文档 | 涵盖内容 | |---|---| | [`docs/commands.md`](docs/commands.md) | **命令备忘录** （Claude/Codex/技能/工具的命令、技能、MCP、质量门控……） | | [`docs/getting-started.md`](docs/getting-started.md) | 添加子模块、运行 `bootstrap.sh`、打开 DevContainer、标志、验证。 | | [`docs/updating.md`](docs/updating.md) | `git submodule update --remote` 如何传播新技能/配置（以及需要重新运行的内容）。 | | [`docs/architecture.md`](docs/architecture.md) | 符号链接与复制的决策、占位符检测、存储库布局。 | | [`docs/windows.md`](docs/windows.md) | Windows 上的符号链接（Developer Mode / `core.symlinks`）以及如何避免 CRLF 问题。 | 工具包中的 [`kit/docs/ai-harness/`](kit/docs/ai-harness/) 文档介绍了 AI 套件（代理、技能、MCP、质量门控、OpenSpec/SDD）。 --- ## 🤝 贡献 个人工具包，但欢迎建议： 1. 开启一个 **问题** 来描述想法/错误。 2. 对于 `kit/` 中的更改，请编辑并在 PR 之前运行验证器： ```bash cd kit && bash scripts/ai/validate-skills.sh && \ bash scripts/ai/validate-claude-agents.sh && bash scripts/ai/validate-codex-agents.sh ``` 3. 保持 **Claude × Codex** 的一致性（`.claude/skills/` **和** `.agents/skills/` 中的新技能）。 4. 脚本采用 **LF** （`.gitattributes` 已保证）；遵循邻近文件的样式。 在 **CC BY-SA 4.0** 下：通过贡献，您同意在相同许可下授权。 ## 📄 许可证 **CC BY-SA 4.0** （知识共享署名-相同方式共享 4.0）— 参见 [`LICENSE`](LICENSE)。 GitHub 认可（SPDX `CC-BY-SA-4.0`）。 - **BY** — 致谢 **Wesley Oliveira Santos** 并引用此项目。 - **SA** — 衍生作品必须保持 **相同许可** 且 **开源** （版权保护）。 > 以前是 CC BY-NC-SA（带有非商业条款），但 GitHub 不为非商业许可证显示徽章。更改为 **无 NC** 版本 — 最接近 GitHub 认可的版本，同时保留署名和“保持开放”。