Code AI Agent Bootstrap V2

面向 大型 Java / Spring / Spring Cloud 项目 的多 CLI AI agent 工作流脚手架。

V2 现在支持用户在初始化时选择：

Codex CLI
Claude Code
OpenCode

核心目标不是让某一个 AI CLI 一次性读完整个仓库，而是把复杂项目拆成可维护、可版本控制、可持续更新的 AI 上下文系统：

脚本确定项目事实
-> 生成 .ai/bootstrap 结构化索引
-> 生成每个模块的 context pack
-> 用户选择 Codex / Claude Code / OpenCode
-> 目标 CLI 读取 bootstrap 仓库 + 目标业务项目
-> 生成多 CLI 通用的 AGENTS.md、.ai/、skills、hook、启动脚本

适合十万行左右的 Java/Spring 老项目、Spring Cloud 微服务项目、带 gateway/framework/service/repository/cache/MQ 的复杂后端工程。

1. 推荐目录布局

把本仓库和你的业务项目放在同一个父目录下：

workspace/
├── code-ai-agent-bootstrap/
└── your-business-project/

推荐使用交互启动器：

首次使用前建议创建 Python 虚拟环境并安装开发/测试依赖：

cd code-ai-agent-bootstrap
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

本项目的扫描和生成脚本只依赖 Python 标准库；requirements.txt 主要用于安装本仓库开发和测试所需的 pytest。

cd code-ai-agent-bootstrap
./bin/ai-start ../your-business-project

它会让你选择：

1) codex    - OpenAI Codex CLI
2) claude   - Claude Code
3) opencode - OpenCode

也可以非交互指定：

./bin/ai-bootstrap ../your-business-project --deep --cli codex
./bin/ai-bootstrap ../your-business-project --deep --cli claude
./bin/ai-bootstrap ../your-business-project --deep --cli opencode

没有安装任何 agent CLI 时，可以先用本地确定性生成：

./bin/ai-bootstrap ../your-business-project --deep --local-template

2. 三种 CLI 的运行方式

2.1 Codex CLI

./bin/ai-bootstrap ../your-business-project --deep --cli codex

执行逻辑类似：

codex exec \
  --cd ../your-business-project \
  --add-dir . \
  --sandbox workspace-write \
  --ask-for-approval never \
  "...workflow synthesis prompt..."

2.2 Claude Code

./bin/ai-bootstrap ../your-business-project --deep --cli claude

执行逻辑类似：

claude -p \
  --add-dir . \
  --permission-mode plan \
  "...workflow synthesis prompt..."

可以调整权限模式：

./bin/ai-bootstrap ../your-business-project \
  --deep \
  --cli claude \
  --claude-permission-mode acceptEdits

2.3 OpenCode

./bin/ai-bootstrap ../your-business-project --deep --cli opencode

执行逻辑类似：

opencode run --dir <workspace-parent> --agent build "...workflow synthesis prompt..."

OpenCode 没有和 Codex/Claude 完全相同的 --add-dir 语义；本脚本默认用 --opencode-cwd-mode parent，也就是在两个同级仓库的父目录执行 opencode run --dir <parent>，并在 prompt 中明确目标项目路径和 bootstrap 仓库路径。需要更严格时可以加 --opencode-cwd-mode target。

为了避免非交互 opencode run 在 bash/edit=ask 时自动拒绝，bootstrap 阶段会临时注入 OpenCode 配置：使用 build agent，并把本次合成流程的权限设为 allow。启动器不会把目标项目现有的 opencode.json 作为 OpenCode 启动配置加载，因此即使目标配置当前无效，也可以通过本次流程修复。这个临时权限不是永久写入目标项目的日常权限配置；启动器会在 agent 运行前后对目标项目的非 workflow 文件做内容哈希比对，如果发现业务源码、构建脚本、配置等非允许路径被改动，会报错并列出文件。

注意：当前脚手架生成的 opencode.json inline command 使用 template 字段；不要改成 prompt，否则当前安装版本的 OpenCode 会报 Missing key command.<name>.template。

3. V2 能生成什么

目标项目中会生成或更新：

your-business-project/
├── AGENTS.md
├── CLAUDE.md
├── opencode.json
├── .codex/
│   └── config.toml
├── .claude/
│   ├── settings.json
│   └── skills/
├── .opencode/
│   ├── commands/
│   │   ├── implement-feature.md
│   │   ├── review-diff.md
│   │   └── finish-task.md
│   └── skills/
├── .ai/
│   ├── bin/
│   │   └── ai-agent
│   ├── cli-workflow.md
│   ├── project-card.md
│   ├── architecture.md
│   ├── module-map.md
│   ├── runtime-and-commands.md
│   ├── coding-conventions.md
│   ├── api-conventions.md
│   ├── db-and-cache.md
│   ├── testing-strategy.md
│   ├── code-review.md
│   ├── change-log.md
│   ├── task-ledger.md
│   ├── bootstrap-report.md
│   ├── bootstrap/
│   │   ├── repo-inventory.json
│   │   ├── repo-inventory.md
│   │   ├── module-candidates.json
│   │   ├── spring-analysis.json
│   │   ├── data-access.json
│   │   ├── test-inventory.json
│   │   ├── context-pack-summary.json
│   │   └── context-packs/
│   │       ├── gateway.context.md
│   │       ├── system-service.context.md
│   │       └── framework.context.md
│   ├── modules/
│   │   ├── gateway.md
│   │   ├── system-service.md
│   │   └── framework.md
│   └── decisions/
│       └── ADR-0000-ai-workflow-bootstrap.md
├── .agents/
│   └── skills/
│       ├── spring-api-change/
│       ├── sql-index-review/
│       ├── testing-policy/
│       ├── db-cache-mq-analysis/
│       ├── code-review/
│       └── finish-task-and-update-memory/
└── .githooks/
    └── pre-commit

.agents/skills 是跨 CLI 的通用 skill 层；同时会复制到 .claude/skills 和 .opencode/skills，方便 Claude Code / OpenCode 原生发现。

4. 常用命令

4.1 交互选择 CLI 并完整初始化

./bin/ai-start ../your-business-project

4.2 指定 CLI 完整初始化

--cli 是 --agent-cli 的短别名，二者等价。

./bin/ai-bootstrap ../your-business-project --deep --cli codex
./bin/ai-bootstrap ../your-business-project --deep --agent-cli claude
./bin/ai-bootstrap ../your-business-project --deep --cli opencode

流程：

deep-scan -> selected CLI workflow synthesis -> verify

启动器会显示主要文件处理进度，包括仓库事实读取、模块检测、每个模块 context pack 写入、本地 workflow 文件写入、agent 输出保存和 verify 结果。

4.3 本地确定性生成

./bin/ai-bootstrap ../your-business-project --deep --local-template

这不会调用 Codex / Claude / OpenCode，但会使用扫描结果本地生成一套可用的多 CLI 配置。

4.4 只扫描，不生成最终工作流

./bin/ai-bootstrap ../your-business-project --deep-scan

生成：

.ai/bootstrap/repo-inventory.json
.ai/bootstrap/module-candidates.json
.ai/bootstrap/spring-analysis.json
.ai/bootstrap/data-access.json
.ai/bootstrap/test-inventory.json
.ai/bootstrap/context-packs/*.context.md

4.5 对复杂项目只分析指定模块

./bin/ai-bootstrap ../your-business-project \
  --deep \
  --cli claude \
  --include "gateway,system-management-service,framework" \
  --exclude "demo,example,deprecated"

4.6 控制分析模块数量

./bin/ai-bootstrap ../your-business-project --deep --max-modules 30

4.7 只综合工作流

当前项目已有 .ai/bootstrap/ 扫描产物时：

./bin/ai-bootstrap ../your-business-project --synthesize-workflow --cli opencode

本地综合：

./bin/ai-bootstrap ../your-business-project --synthesize-workflow --local-template

4.8 验证生成结果

./bin/ai-bootstrap ../your-business-project --verify

4.9 只打印命令和 prompt

./bin/ai-bootstrap ../your-business-project --deep --cli claude --dry-run --save-prompt

生成的 prompt 会保存到：

code-ai-agent-bootstrap/.runs/

5. 目标项目初始化后的日常开发

进入目标项目后可以直接用统一启动脚本：

cd ../your-business-project
.ai/bin/ai-agent

也可以直接指定：

.ai/bin/ai-agent --cli codex
.ai/bin/ai-agent --cli claude
.ai/bin/ai-agent --cli opencode

非交互任务：

.ai/bin/ai-agent --cli codex --task "按照项目规则实现这个需求，完成后补测试并更新记忆：..."
.ai/bin/ai-agent --cli claude --task "先分析调用链并给出修改计划：..."
.ai/bin/ai-agent --cli opencode --task "Review current diff and update memory if needed."

建议给 AI 的需求格式：

按照当前项目的 AGENTS.md 和 .ai/ 记忆文件处理下面需求。

需求：

【写你的需求】

要求：

1. 先读取 AGENTS.md、.ai/project-card.md、.ai/module-map.md 和相关 .ai/modules/*.md。
2. 先输出调用链、影响范围和修改计划。
3. 不要做无必要的大规模重构。
4. 涉及数据库、缓存、MQ、事务、权限、远程调用时，必须单独说明风险。
5. 修改后运行相关测试；无法运行时说明原因和应运行的命令。
6. 最后更新 .ai/change-log.md、.ai/task-ledger.md 和相关模块记忆。
7. 最后自审 diff，列出风险点。

6. 脚本模块说明

scripts/
├── code_bootstrap.py              # CLI 主入口，编排 scan / synthesize / verify
├── cli_adapters.py                # Codex / Claude Code / OpenCode 命令适配层
├── repo_inventory.py              # 仓库级事实扫描
├── module_detector.py             # Maven/Gradle/Spring/前端模块识别
├── spring_analyzer.py             # Spring Controller/Service/Repository/API/事务分析
├── db_analyzer.py                 # Entity/Repository/SQL/Redis/cache/MQ/scheduled 扫描
├── test_analyzer.py               # 测试框架和模块测试命令识别
├── context_pack_builder.py        # 生成 .ai/bootstrap/context-packs/*.context.md
├── workflow_synthesizer.py        # 本地确定性生成多 CLI 工作流
├── verify_generated_workflow.py   # 校验目标项目工作流是否完整
└── project_probe.py               # V1 兼容轻量扫描入口

所有脚本只依赖 Python 标准库。

7. 对 Spring 项目能识别什么

V2 会尽量从源码和构建文件中识别：

Maven 父子模块、Gradle settings 模块
Spring Boot 应用模块
Spring Cloud Gateway 模块
framework/common/api/client/dto 模块
@RestController、@RequestMapping、@GetMapping、@PostMapping
@Service、@Repository、@Mapper
@Transactional
@FeignClient
JPA Entity / @Table / @Column
JpaRepository / CrudRepository / MyBatis Mapper
@Query / @Select / createSQLQuery / JdbcTemplate
Redis / Redisson / Spring Cache
RabbitMQ / Kafka / RocketMQ
@Scheduled
JUnit / Mockito / SpringBootTest / MockMvc / Testcontainers

扫描结果会被写入 .ai/bootstrap/*.json 和 .ai/bootstrap/context-packs/*.context.md，给后续任意 CLI 使用。

8. 为什么适合十万行项目

大型项目不适合让 AI 每次全仓库乱读。V2 会把目标项目切成几层：

AGENTS.md                         # 简短总规则
.ai/project-card.md               # 项目身份证
.ai/module-map.md                 # 模块导航
.ai/bootstrap/*.json              # 脚本扫描出的事实
.ai/bootstrap/context-packs/*.md  # 模块压缩上下文
.ai/modules/*.md                  # 长期模块记忆
.agents/skills/*/SKILL.md         # 可复用专项工作流
.ai/change-log.md                 # 每次改动的长期记录
.ai/task-ledger.md                # 当前任务状态

后续任意 CLI 做需求时，不需要“重新理解全项目”，而是：

读取 AGENTS.md
-> 读取 project-card
-> 读取 module-map
-> 定位目标模块
-> 读取对应 module memory 和 context pack
-> 搜索真实调用链
-> 小步修改
-> 测试/自审
-> 更新 .ai 记忆

9. 启用 Git hook

初始化后在目标项目中执行：

cd ../your-business-project
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

之后如果修改了代码但没有更新 .ai/change-log.md 或相关 .ai/modules/*.md，提交会被拦截。

临时跳过：

AI_MEMORY_SKIP=1 git commit -m "format only"

10. 安全边界

不给 AI 生产库写权限。
不把 token、密码、生产连接、私钥写入 .ai/。
DDL、删除数据、线上发布、重启服务必须人工确认。
AI CLI 可以写代码、补测试、更新记忆，但开发者必须审阅 diff 和风险。

11. 开发本 bootstrap 项目

首次准备开发环境：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

之后运行测试：

python3 -m pytest -q

V2 当前测试覆盖：

V1 probe 兼容
legacy prompt/template 兼容
Spring 多模块 deep scan
context pack 生成
本地 workflow synthesize
workflow verify
多 CLI 命令适配

12. 上传 GitHub

cd code-ai-agent-bootstrap
git init
git add .
git commit -m "init multi cli ai agent bootstrap v2"
git branch -M main
git remote add origin git@github.com:YOUR_NAME/code-ai-agent-bootstrap.git
git push -u origin main

13. 设计原则

不让 AI 靠聊天记忆硬撑，而是把项目事实、模块记忆、变更记录、测试约束、审查标准全部沉淀到仓库里，让 Codex CLI、Claude Code 或 OpenCode 每次重新读取。

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
bin		bin
examples		examples
prompts		prompts
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Navigation Menu

Repository files navigation

Code AI Agent Bootstrap V2

1. 推荐目录布局

2. 三种 CLI 的运行方式

2.1 Codex CLI

2.2 Claude Code

2.3 OpenCode

3. V2 能生成什么

4. 常用命令

4.1 交互选择 CLI 并完整初始化

4.2 指定 CLI 完整初始化

4.3 本地确定性生成

4.4 只扫描，不生成最终工作流

4.5 对复杂项目只分析指定模块

4.6 控制分析模块数量

4.7 只综合工作流

4.8 验证生成结果

4.9 只打印命令和 prompt

5. 目标项目初始化后的日常开发

6. 脚本模块说明

7. 对 Spring 项目能识别什么

8. 为什么适合十万行项目

9. 启用 Git hook

10. 安全边界

11. 开发本 bootstrap 项目

12. 上传 GitHub

13. 设计原则

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Code AI Agent Bootstrap V2

1. 推荐目录布局

2. 三种 CLI 的运行方式

2.1 Codex CLI

2.2 Claude Code

2.3 OpenCode

3. V2 能生成什么

4. 常用命令

4.1 交互选择 CLI 并完整初始化

4.2 指定 CLI 完整初始化

4.3 本地确定性生成

4.4 只扫描，不生成最终工作流

4.5 对复杂项目只分析指定模块

4.6 控制分析模块数量

4.7 只综合工作流

4.8 验证生成结果

4.9 只打印命令和 prompt

5. 目标项目初始化后的日常开发

6. 脚本模块说明

7. 对 Spring 项目能识别什么

8. 为什么适合十万行项目

9. 启用 Git hook

10. 安全边界

11. 开发本 bootstrap 项目

12. 上传 GitHub

13. 设计原则

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages