Init Project（项目初始化文档生成器）

目标

为全新项目快速生成规范的 AI 项目指令文档，使 AI 助手（Claude Code / OpenAI Codex CLI）能够理解项目目标、遵循工程原则、按预期行为协作。

生成文件

重要说明：

1. AGENTS.md 是唯一需要手动维护的项目指令文件

   • 包含跨平台通用的核心指令
   • 符合 AGENTS.md 标准（60k+ 开源项目采用）
   • 支持 OpenAI Codex、Google Jules、Cursor、Devin、Windsurf 等 20+ 工具

2. CLAUDE.md 通过 @./AGENTS.md 语法自动引用

   • 修改 AGENTS.md 后，CLAUDE.md 自动生效
   • 无需运行任何同步命令
   • 仅包含 Claude Code 特定的适配内容

3. CHANGELOG.md 是项目管理的强制性要求

   • 凡是项目的更新，都要统一在 CHANGELOG.md 文件里记录
   • 遵循 Keep a Changelog 格式

核心特性

• 完全自动化：一键生成，无需手动输入信息
• 智能项目分析：自动检测项目类型（Python/Web/Rust/Go/Java/数据科学/文档等）
• 跨平台通用：生成符合 AGENTS.md 标准的跨平台指令文件
• 零维护成本：CLAUDE.md 通过 @./AGENTS.md 自动引用，修改 AGENTS.md 即可
• 自动语言检测：检测操作系统默认语言并设为对话默认语言
• 目录结构推断：分析现有文件和目录，自动生成目录树（用于 README.md；CLAUDE.md 仍可包含，AGENTS.md 默认不再包含）
• README 解析与生成：从 README.md 提取信息，或自动生成项目介绍
• 强制变更记录：自动创建 CHANGELOG.md，这是项目管理的强制性要求
• 工程原则内置：基于 SOLID、KISS、DRY、YAGNI、关注点分离等原则
• 有机更新框架：生成的文档本身遵循有机更新原则，便于未来迭代
• 智能增量更新：对已存在的 AGENTS.md，自动保留用户自定义内容，仅更新标准化部分
• 符合社区标准：遵循 AGENTS.md 官方规范，与 60k+ 开源项目保持一致

AGENTS.md 与 CLAUDE.md 的关系

核心原则：AGENTS.md 是跨平台通用项目指令（Single Source of Truth），CLAUDE.md 通过 @./AGENTS.md 语法自动引用。

架构设计

项目根目录/
├── AGENTS.md              # 跨平台通用指令（手动维护）
│   ├── 项目目标
│   ├── 核心工作流
│   ├── 工程原则
│   ├── 默认语言
│   ├── 变更边界
│   └── 有机更新原则
│
└── CLAUDE.md              # Claude Code 特定适配（自动引用）
    ├── @./AGENTS.md       # 自动引用 AGENTS.md 的全部内容
    └── Claude Code 特定说明
        ├── 文件引用规范（markdown 链接语法）
        ├── 任务管理（TodoWrite 工具）
        └── 代码变更规范（Read/Edit 工具）

维护工作流

标准流程：

1. 修改 AGENTS.md（唯一需要手动维护的文件）
2. CLAUDE.md 自动生效（无需任何操作）
3. 记录变更到 CHANGELOG.md

优势：

• ✅ 零维护成本：修改 AGENTS.md 后，CLAUDE.md 自动生效
• ✅ Single Source of Truth：AGENTS.md 是唯一的事实来源
• ✅ 符合社区标准：遵循 AGENTS.md 官方规范
• ✅ 跨平台兼容：AGENTS.md 支持 20+ AI 编码工具

Claude Code 的 @ 引用语法

根据 Claude Code Issue #990，Claude Code 支持 @ 语法来引用其他文件：

# CLAUDE.md

## 核心指令

@./AGENTS.md

## Claude Code 特定说明
...

工作原理：

• Claude Code 启动时，会自动将 @./AGENTS.md 引用的文件内容”拉入”上下文
• 修改 AGENTS.md 后，CLAUDE.md 会自动读取最新内容
• 无需运行任何同步命令或构建步骤

触发条件

用户明确表示要：

• 初始化一个新项目
• 创建项目配置文件
• 生成 AGENTS.md / CLAUDE.md
• 为现有项目补全项目指令文档
• 自动生成项目文档

执行方式

方式一：完全自动化（推荐）

直接运行脚本，自动分析当前目录并生成文档：

python3 init-project/scripts/generate.py --auto

脚本会自动完成：

1. 检测项目类型（通过 pyproject.toml、package.json、Cargo.toml 等标志文件）
2. 从 README.md 提取项目名称和描述（如存在）
3. 生成目录树（自动过滤 .git、node_modules、pycache 等）
4. 检测操作系统语言
5. 生成 AGENTS.md（跨平台通用项目指令）
6. 生成 CLAUDE.md（使用 @./AGENTS.md 引用 + Claude Code 特定适配）
7. 检查并生成 README.md（如不存在）
8. 检查并生成 CHANGELOG.md（如不存在）

方式二：通过 Claude Code 触发

在 Claude Code 中触发本 skill 后：

1. 运行自动模式：

   python3 init-project/scripts/generate.py --auto
   

2. 如需覆盖现有文件：

   python3 init-project/scripts/generate.py --auto --overwrite
   

3. 仅生成指定文件：

   # 仅生成 AGENTS.md 和 CLAUDE.md（CHANGELOG.md 仍会生成，因为它是强制性的）
   python3 init-project/scripts/generate.py --auto --skip-readme
   
   # 仅更新 README.md
   python3 init-project/scripts/generate.py --auto --only-readme
   
   # 注意：不建议使用 --skip-changelog，因为 CHANGELOG.md 是强制性的
   

工作流程

自动模式流程

当使用 --auto 参数时，脚本执行以下流程：

1. 项目类型检测

扫描目录中的标志性文件，自动识别项目类型：

2. 项目信息提取

• 项目名称：优先从 README.md 的标题提取，回退到目录名
• 项目描述：从 README.md 第一段提取，回退到默认模板
• 目录树：自动生成（最大深度 2 层），过滤常见忽略项

3. 语言检测

自动检测操作系统语言并映射到对话语言。

4. 生成 AI 指令文档

根据检测到的项目类型，使用对应的工作流模板：

生成顺序：

1. AGENTS.md：跨平台通用项目指令（Single Source of Truth）
2. CLAUDE.md：使用 @./AGENTS.md 引用 + Claude Code 特定适配

5. 检查并生成 README.md

• 如果 README.md 不存在：自动生成项目介绍
• 如果 README.md 已存在：跳过（除非使用 --overwrite）

README.md 内容：

• 项目名称和描述
• 主要功能和特性
• 快速开始指南
• 目录结构说明
• AI 辅助开发说明（如何使用 Claude Code / Codex）

6. 检查并生成 CHANGELOG.md（强制性）

• 如果 CHANGELOG.md 不存在：自动创建初始版本
• 如果 CHANGELOG.md 已存在：追加新的更改记录

CHANGELOG.md 是项目管理的强制性要求：

• 重要原则：凡是项目的更新，都要统一在 CHANGELOG.md 文件里记录
• 记录范围：
  • 项目指令文件变更（CLAUDE.md、AGENTS.md 的任何修改）
  • 项目结构变更（新增/删除/重命名目录或关键文件）
  • 工作流变更（核心工作流程的调整）
  • 工程原则变更（新增、修改或删除工程原则）
  • 重要配置变更（影响项目行为的配置文件修改）
• 遵循 Keep a Changelog 格式
• 记录时机：
  • 修改前：先在 [Unreleased] 部分草拟变更内容
  • 修改后：完善变更描述，添加具体细节和影响范围

手动模式流程（可选）

如需手动指定信息，使用命令行参数：

python3 scripts/generate.py \
  --project-name "my-project" \
  --project-description "数据科学项目" \
  --workflow "数据获取 → 分析 → 可视化"

输出规范

生成的文档包含以下内容：

模板来源（Single Source of Truth）

为避免在 SKILL.md 内堆叠大段模板文本（社区推荐：SKILL.md ≤ 500 行），本技能的输出模板统一放在 init-project/templates/：

• AGENTS.md：init-project/templates/AGENTS.md.template
• CLAUDE.md：init-project/templates/CLAUDE.md.template（核心：@./AGENTS.md 引用 AGENTS.md）
• README.md：init-project/templates/README.md.template
• CHANGELOG.md：init-project/templates/CHANGELOG.md.template

脚本会基于项目分析结果替换模板占位符；当目标文件已存在时，按本文后续的“智能合并策略”处理。

CHANGELOG.md 更新规则（强制性）：

• 每次修改 CLAUDE.md 或 AGENTS.md 时，必须追加记录
• 记录修改原因、具体变更内容、影响范围
• 使用语义化版本号（推荐）
• 记录时机：修改前草拟，修改后完善
• 记录质量：清晰具体、可追溯、格式统一、及时更新

配置参数（config.yaml）

本技能使用 config.yaml 管理语言映射和默认模板。

错误处理

• CLAUDE.md / AGENTS.md 已存在：默认启用智能合并模式
  • 保留：用户自定义的项目目标、核心工作流、变更边界、自定义章节
  • 更新：工程原则、默认语言、平台特定说明（目录结构仅适用于仍包含该章节的文件，如 CLAUDE.md）
  • 强制覆盖：使用 --overwrite 参数完全替换现有内容
• README.md 已存在：默认跳过，使用 --overwrite 覆盖
• 语言检测失败：回退到简体中文
• 无法识别项目类型：使用通用项目模板

智能合并策略

当 CLAUDE.md 或 AGENTS.md 已存在时，脚本会自动进行智能合并：

保留的用户自定义内容

• ## 项目目标 章节中的自定义描述（排除默认模板内容）
• ## 核心工作流 章节中的自定义工作流
• ## 变更边界 章节中的自定义规则
• 用户添加的自定义章节（不在标准模板中的章节）

更新的标准化内容

• ## 工程原则：更新为最新的工程原则标准
• ## 默认语言：更新为检测到的语言
• ## 目录结构：仅对仍包含该章节的文件更新为最新目录树（AGENTS.md 默认不再包含该章节）
• 平台特定说明：Claude Code / Codex CLI 特定部分

示例

假设用户已在 CLAUDE.md 中自定义了项目目标和工作流：

## 项目目标
开发一个高性能的数据处理引擎，支持实时流处理和批量处理。
（这是用户自定义的内容）

## 核心工作流
需求分析 → 架构设计 → 核心开发 → 性能测试 → 部署上线
（这是用户自定义的工作流）

再次运行 init-project 时，这些自定义内容会被保留，而工程原则、默认语言、平台特定说明等标准化内容会被更新（AGENTS.md 的旧「目录结构」章节会被移除）。

使用示例

场景 1：全新项目（完全自动化）

# 在项目根目录执行
python3 init-project/scripts/generate.py --auto

# 输出示例：
# ✅ 已生成项目初始化文档:
#    - /path/to/project/AGENTS.md
#    - /path/to/project/CLAUDE.md
#
# 📊 项目分析结果:
#    名称: my-project
#    类型: Python 项目
#    语言: 简体中文

场景 2：现有项目补全文档（智能合并）

# 在现有项目目录执行（CLAUDE.md 和 AGENTS.md 已存在）
python3 init-project/scripts/generate.py --auto

# 输出示例：
# 🔄 /path/to/project/CLAUDE.md 已智能更新（保留了自定义内容）
# 🔄 /path/to/project/AGENTS.md 已智能更新（保留了自定义内容）
# ✅ 已生成 AI 项目指令文档:
#    - /path/to/project/CLAUDE.md
#    - /path/to/project/AGENTS.md
#
# 📊 项目分析结果:
#    名称: my-project
#    类型: Python 项目
#    语言: 简体中文

场景 3：覆盖现有文档（完全替换）

python3 init-project/scripts/generate.py --auto --overwrite

# 输出示例：
# ✅ 已生成 AI 项目指令文档:
#    - /path/to/project/CLAUDE.md
#    - /path/to/project/AGENTS.md

验证清单（交付前）

• 语言检测正确或用户已覆盖
• 项目信息完整（名称、目标、用途）
• AGENTS.md 包含所有必需章节（包括变更记录规范）
• CLAUDE.md 与 AGENTS.md 引用关系正确
• 工程原则章节完整
• 有机更新原则已包含
• 变更记录规范已明确（CHANGELOG.md 强制性要求）
• 文件已成功写入磁盘
• CHANGELOG.md 已创建（强制性）

有机更新原则

当需要更新本文档时：

1. 理解意图：用户真正想解决什么问题？
2. 定位生态位：更新应该放在哪个位置？
3. 协调更新：同步更新相关章节（如有）
4. 保持一致性：术语、示例、引用保持统一