Init Project
与 bensz-collect-bugs 的协作约定
- 因本 skill 设计缺陷导致的 bug，先用
bensz-collect-bugs记录到~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续任务。 - 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地
gh上传新增 bug 到huangwb8/bensz-bugs；不要 pull / clone 整个仓库。
目标与边界
为当前项目生成标准 AI 协作文档，让 Claude Code / OpenAI Codex CLI 等工具理解项目目标、工程原则、变更记录规则与协作边界。
只允许在当前工作目录及其子目录内创建或修改文件。禁止写入父目录、其它项目、系统目录或用户级配置。脚本会在写入前校验输出路径，失败时立即停止。
输出文件
| 文件/目录 | 用途 | 默认行为 |
|---|---|---|
AGENTS.md | 跨平台通用项目指令，Single Source of Truth | 必生成，智能合并 |
CLAUDE.md | Claude Code 适配层，核心为 @./AGENTS.md | 必生成，智能合并 |
README.md | 项目介绍与快速开始 | 不存在时生成，--overwrite 可覆盖 |
CHANGELOG.md | 项目变更记录 | 不存在时生成；项目变更必须维护 |
.gitignore | 安全优先的忽略规则 | 不存在时生成，覆盖模式下智能合并 |
docs/、docs/plans/ | 文档根目录与计划文档目录 | 完整初始化时自动补齐 |
docs/contribution.bac | BAC 贡献记录账本 | 默认启用；--bac-file 可改，--disable-bac 可关 |
核心约束
AGENTS.md是唯一需要长期手动维护的通用指令源；CLAUDE.md只做 Claude Code 适配，并通过@./AGENTS.md自动引用。- 生成模板统一放在
init-project/templates/：AGENTS.md.template、CLAUDE.md.template、README.md.template、CHANGELOG.md.template、gitignore.yaml。 - 配置统一放在
init-project/config.yaml，版本号以skill_info.version为准；当前 BAC 配置在bac_contribution。 - 完整初始化必须补齐
docs/与docs/plans/；计划文档固定放在./docs/plans/。 - 代码变化导致
docs/中非plans/文档过时时，生成的项目指令必须要求同步更新。 - 影响项目行为、结构、工作流、工程原则、指令文件或关键配置的变更，必须写入
CHANGELOG.md的[Unreleased]。
BAC 贡献记录
默认基于 bensz-auto-contribution / bac 记录人类、AI 与工具贡献证据：
- 默认仓库：
https://github.com/huangwb8/bensz-auto-contribution - 默认安装源：
git+https://github.com/huangwb8/bensz-auto-contribution.git - 默认文件：
docs/contribution.bac - Python 要求：
config.yaml:bac_contribution.min_python_version，当前为3.10 - 默认开启；用户可随时通过
--disable-bac显式关闭。关闭时生成的文档也必须说明当前已关闭且可重新启用。 - 用户通过
--bac-file指定项目内其它路径时，以用户指定为准；禁止把.bac文件写到项目目录外。
BAC 是过程记录与辅助审计材料，不替代最终署名、责任或合规判断；不得记录敏感密钥、完整私有提示词或无关个人隐私。
推荐执行
在目标项目根目录运行：
python3 init-project/scripts/generate.py --auto
常用参数：
# 覆盖/强制更新已有文件
python3 init-project/scripts/generate.py --auto --overwrite
# 指定 BAC 文件，必须位于项目目录内
python3 init-project/scripts/generate.py --auto --bac-file docs/audit/contribution.bac
# 显式关闭默认 BAC 初始化
python3 init-project/scripts/generate.py --auto --disable-bac
# 只生成单类文档
python3 init-project/scripts/generate.py --auto --only-readme
python3 init-project/scripts/generate.py --auto --only-changelog
# 跳过可选输出
python3 init-project/scripts/generate.py --auto --skip-readme --skip-gitignore
手动模式只在用户明确给出项目信息时使用：
python3 init-project/scripts/generate.py \
--project-name "my-project" \
--project-description "数据科学项目" \
--workflow "数据获取 → 分析 → 可视化"
自动模式流程
--auto 会依次完成：
- 验证输出目录必须位于当前工作目录内。
- 分析项目：从 README 提取名称/描述，按标志文件识别 Python/Web/Rust/Go/Java/数据科学/文档/通用项目，生成最多 2 层目录树。
- 检测默认语言，失败时回退到简体中文。
- 完整初始化时创建
docs/与docs/plans/。 - 按配置决定是否启用 BAC：检查 Python 与
bac包，必要时安装，初始化或验证.bac文件。 - 生成或智能合并
AGENTS.md、CLAUDE.md。 - 按条件生成
README.md、CHANGELOG.md、.gitignore。 - 输出生成文件、目录与项目分析摘要。
项目类型识别标志：
| 类型 | 标志 |
|---|---|
| Python | pyproject.toml、requirements.txt、setup.py、setup.cfg、__init__.py |
| Web | package.json、yarn.lock、pnpm-lock.yaml、webpack.config.js |
| Rust | Cargo.toml、Cargo.lock |
| Go | go.mod、go.sum |
| Java | pom.xml、build.gradle、build.gradle.kts |
| 数据科学 | *.ipynb、*.R、environment.yml |
| 文档 | docs/、_docs/、mkdocs.yml、docusaurus.config.js |
智能合并策略
当 AGENTS.md 或 CLAUDE.md 已存在时，默认智能合并而非直接覆盖。
保留：
- 用户自定义的
## 项目目标、## 核心工作流、## 变更边界 - 不属于标准模板的用户自定义章节
更新：
- 工程原则、默认语言、平台适配说明
AGENTS.md必需章节清单对应的标准章节CLAUDE.md的@./AGENTS.md引用关系
兼容处理：
AGENTS.md中历史遗留的## 目录结构会被丢弃，避免回填为自定义章节。- 合并不符合预期时，提示用户用
--overwrite完全覆盖。
.gitignore 策略
从 templates/gitignore.yaml 读取规则；缺少 PyYAML 或配置损坏时使用默认规则兜底。安全优先，默认忽略系统文件、IDE 配置、日志、临时文件、环境变量、密钥、凭证目录和常见构建/缓存产物。已有 .gitignore 在覆盖模式下会保留用户自定义规则。
错误处理
- 输出目录越界、目标目录不存在或不是目录：停止。
docs/docs/plans已存在但不是目录：停止。- BAC 安装、导入、初始化或验证失败：停止，并提示可用
--disable-bac显式关闭。 - 语言检测失败：回退到简体中文。
- 项目类型无法识别：使用通用项目模板。
PyYAML缺失：脚本继续运行，配置与.gitignore使用默认值。
交付前检查
-
AGENTS.md包含必需章节：项目目标、核心工作流、工程原则、默认语言、联网与搜索、贡献记录、Codex CLI 特定说明、变更记录与版本、有机更新原则。 -
CLAUDE.md正确通过@./AGENTS.md引用通用指令。 -
docs/、docs/plans/已存在或无需本模式创建。 - BAC 已初始化/验证，或用户已显式使用
--disable-bac。 -
.gitignore已生成/合并，且包含敏感文件忽略规则。 -
CHANGELOG.md已创建或变更已记录。 - 未写入当前项目目录之外的文件。