project-docs SKILL 使用指南

本目录包含项目文档管理的 AI Skills，支持 Claude Code 和 Codex 两种客户端。

NPM 安装（推荐）

npm install -g @longjunzhang/project-docs-skills

安装后，skills 会自动复制到：

• Claude: ~/.claude/skills/
• Codex: ~/.codex/skills/

重新安装会自动覆盖旧版本，无需手动清理。

脚本安装（本地）

下载项目后，切换到 ai-prompt/project-docs 目录，执行：

chmod +x check-env.sh
bash check-env.sh

脚本会自动检测操作系统、校验依赖（Git、jq）、检测已安装的 AI 客户端并安装 skills。

Windows 用户注意: 需要使用 Git Bash 运行，不支持 PowerShell 或 CMD。 (Windows 安装 Git Bash: winget install --id Git.Git -e --source winget)

前置依赖

• Git - 版本控制
• jq - JSON 处理工具

安装方法:

• macOS: brew install git jq
• Linux: sudo apt-get install git jq
• Windows: winget install --id jqlang.jq -e --source winget

安装位置

• Claude: ~/.claude/skills/
• Codex: ~/.codex/skills/

脚本会自动检测已安装的客户端并安装到对应位置。

生成文档结构

项目根目录/
├── CLAUDE.md              ← Claude Code 索引入口（See @AGENTS.md for project overview）
├── AGENTS.md              ← 主文档：技术约束、构建命令、项目概述、文档路由
└── agent_docs/
    ├── entry-points.md    ← 业务入口清单
    ├── [模块名].md        ← 各业务模块详细文档
    ├── config.md          ← 配置来源说明
    └── docs-version.json  ← 版本追踪文件

• CLAUDE.md 是 Claude Code 的自动入口，通过 See @AGENTS.md 语法引用主文档
• AGENTS.md 是社区通用的 AI 文档标准，通过 See @agent_docs/xxx.md for xxx 语法引用子文档
• 这种分层结构让 AI 按需读取，避免一次性加载全部内容

Skills 列表

| Skill | 说明 | |-------|------| | project-docs-init | 首次生成 CLAUDE.md + AGENTS.md + agent_docs/ 文档 | | project-docs-update | 基于 Git diff 增量更新文档 | | project-docs-clean | 安全删除所有 AI 文档（需确认） | | project-docs-rebuild | 用最新模板重建文档，保留"常见误区" |

使用场景

| 场景 | 使用命令 | 说明 | |------|---------|------| | 空项目 | ❌ 不可用 | 需先创建构建文件（package.json/pom.xml 等）和 Git 提交 | | 新项目（有代码无文档） | project-docs-init | 首次生成 CLAUDE.md + AGENTS.md + agent_docs/ | | 历史项目（无文档） | project-docs-init | 分析现有代码生成文档 | | 文档已存在，代码有变更 | project-docs-update | 基于 Git diff 增量更新 | | 合并到 master 后 | project-docs-update | 自动或手动更新文档版本 | | 代码无变更 | project-docs-update | 跳过更新，提示已是最新 | | Skill 模板升级后 | project-docs-rebuild | 用新模板重建，保留沉淀内容 | | 不再需要 AI 文档 | project-docs-clean | 安全删除，可通过 Git 恢复 |

调用方式

Claude Code

交互模式：

# 建议先切换到 opus 模型
/project-docs-init
/project-docs-update
/project-docs-clean
/project-docs-rebuild

无头命令：

claude --model 'opus' --effort 'max' -p '/project-docs-init'
claude --model 'opus' --effort 'max' -p '/project-docs-update'
claude --model 'opus' --effort 'max' -p '/project-docs-clean'
claude --model 'opus' --effort 'max' -p '/project-docs-rebuild'

Codex

交互模式：

# 建议先切换到 gpt-5.4 high(xhigh) 模型
$project-docs-init
$project-docs-update
$project-docs-clean
$project-docs-rebuild

无头命令：

codex -m 'gpt-5.4' -c model_reasoning_effort='high' exec '$project-docs-init'
codex -m 'gpt-5.4' -c model_reasoning_effort='high' exec '$project-docs-update'
codex -m 'gpt-5.4' -c model_reasoning_effort='high' exec '$project-docs-clean'
codex -m 'gpt-5.4' -c model_reasoning_effort='high' exec '$project-docs-rebuild'

CI 集成

GitLab CI

在 .gitlab-ci.yml 中添加自动更新任务：(需要在 GitLab 中配置 Claude Code/Codex API)

update-docs:
  stage: deploy
  only:
    - master
  script:
    - claude -p '/project-docs-update'
    # 或 codex exec '$project-docs-update'
  after_script:
    - |
      if git diff --quiet; then
        echo "文档无变更"
      else
        git config user.name "CI Bot"
        git config user.email "[email protected]"
        git add CLAUDE.md AGENTS.md agent_docs/
        git commit -m "docs: 自动更新项目文档 [skip ci]"
        git push origin master
      fi