npm package: @longjunzhang/project-docs-skills
Description: AI project documentation skills for Claude/Codex - init, update, clean, and rebuild
Author: hstong
Latest version: 1.0.0

# project-docs SKILL 使用指南

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

## NPM 安装（推荐）

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

安装后，skills 会自动复制到：
- Claude: `~/.claude/skills/`
- Codex: `~/.codex/skills/`

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

## 脚本安装（本地）

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

```bash
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

**交互模式**：
```bash
# 建议先切换到 opus 模型
/project-docs-init
/project-docs-update
/project-docs-clean
/project-docs-rebuild
```

**无头命令**：
```bash
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

**交互模式**：
```bash
# 建议先切换到 gpt-5.4 high(xhigh) 模型
$project-docs-init
$project-docs-update
$project-docs-clean
$project-docs-rebuild
```

**无头命令**：
```bash
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)

```yaml
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 "ci@example.com"
        git add CLAUDE.md AGENTS.md agent_docs/
        git commit -m "docs: 自动更新项目文档 [skip ci]"
        git push origin master
      fi
```