GitHub: github.com/Leo-skye-ta…
⭐ 如果对你有启发，欢迎 Star 支持！
写在前面
一个多月前，我给 Claude Code 写了个自动文档插件，发到小红书后居然有 1000+ 阅读。
但用下来发现一个问题：过度依赖 Shell 脚本。
hooks、scripts 目录里堆了 10+ 个 .sh 文件，维护成本高，而且 AI 只是"调用者"，不是"思考者"。
v3.0.0 我做了一个激进的决定：删掉所有脚本，让 AI 完全接管。
v2.x 的问题：脚本驱动的尴尬
旧架构（hooks + scripts）
hooks/
├── force-archive.sh # 强制归档
├── post-edit-archive.sh # 编辑后归档
├── pre-edit-check.sh # 编辑前检查
└── stop-check.sh # 停止检查
scripts/
├── enforce-workflow.sh # 强制工作流
├── record-changes.sh # 记录变更
├── scan-codebase.sh # 扫描代码库
├── setup-rules.sh # 设置规则
├── validate-reading.sh # 验证阅读
└── (还有 3 个...)
问题在哪？
- AI 只是"按钮"：脚本写死了逻辑，AI 只能按脚本走，无法灵活应对
- 维护成本高：10+ 个 Shell 脚本，改一个影响一片
- 无法增量更新：每次全量扫描，慢
- 不 AI-native：既然用 Claude Code，为啥还要写 Shell？
v3.0.0 重构：AI-Driven 架构
新架构（skill-command-driven）
删掉的全部内容（6700+ 行）：
❌ hooks/ (4个 Shell 脚本，全删)
❌ scripts/ (6个自动化脚本，全删)
❌ references/ (3个参考文档，全删)
新增的内容（2500+ 行）：
✅ SKILL.md (完整的 AI 指令集，300+ 行)
✅ CLAUDE.md (工作流规则，自动生成)
✅ AGENTS.md (AI Agent 行为规则，自动生成)
✅ .ai-context/ (文档目录结构，AI 自动维护)
核心变化：从"脚本调用 AI"变成"AI 自己决定怎么做"。
两个核心命令
1. /docs-scan — AI 扫描代码库
旧版（v2.x）：
# 跑一个 Shell 脚本，硬编码逻辑
./scripts/scan-codebase.sh
新版（v3.0.0）：
你: /docs-scan
AI: 好的，我现在扫描你的代码库...
[AI 自己决定扫描哪些文件、生成什么文档]
✅ 已生成：
- .ai-context/README.md (项目概览)
- .ai-context/architecture.md (系统架构)
- .ai-context/modules/ (模块文档)
- .ai-context/api/ (API 文档)
AI 会自己做什么？
- 读取项目结构（
ls -la、find等） - 分析核心代码文件（
.js/.ts/.py等） - 自动生成 9 类文档（README、架构、模块、API、数据库、中间件、规范、变更记录、技术决策）
- 增量更新（加
--update参数，只更新变更部分）
2. /code-documents-auto — AI 读文档 + 归档
两种模式：
模式 A：读取模式（开发前）
你: /code-documents-auto 添加用户登录功能
AI: 好的，我先读取相关文档...
[AI 自动读取 .ai-context/ 下的相关文档]
📖 开发方案：
1. 数据库：需要新建 users 表（见 .ai-context/database/）
2. API：需要新增 POST /api/login（见 .ai-context/api/）
3. 中间件：需要新增 authMiddleware（见 .ai-context/middleware/）
开始吗？
模式 B：归档模式（开发后）
你: /code-documents-auto 开发完了，归档
AI: 好的，我总结一下变更...
[AI 自动对比代码变更，更新所有相关文档]
✅ 已更新：
- .ai-context/changelog/2026-06-01-添加用户登录.md
- .ai-context/modules/auth.md
- .ai-context/api/auth.md
归档完成！
实战演示：给项目添加"用户登录"功能
Step 0：首次使用（生成文档）
你: /code-documents-auto
AI: ✅ 文档已生成，请看 .ai-context/ 目录
生成的文档结构：
.ai-context/
├── README.md # 项目概览
├── architecture.md # 系统架构
├── modules/ # 模块文档
├── api/ # API 文档
├── database/ # 数据库设计
├── middleware/ # 中间件使用
├── guidelines/ # 编码规范
├── changelog/ # 变更记录
└── decisions/ # 技术决策
Step 1：开发前（AI 读文档，输出方案）
你: /code-documents-auto 添加用户登录功能
AI: 好的，我先读取相关文档...
📖 开发方案：
【数据库变更】
- 新建 users 表（字段：id, username, password_hash, created_at）
- 见 .ai-context/database/users.md
【API 设计】
- POST /api/auth/register (注册)
- POST /api/auth/login (登录)
- POST /api/auth/logout (登出)
- 见 .ai-context/api/auth.md
【中间件】
- 新建 authMiddleware（验证 JWT）
- 见 .ai-context/middleware/auth.md
【编码规范】
- 密码必须 bcrypt 加密
- JWT secret 放环境变量
- 见 .ai-context/guidelines/security.md
开始开发吗？
Step 2：开发（你写代码，AI 不插手）
# 你自己写代码，Claude Code 不干预
npm install bcrypt jsonwebtoken
# ... 实现登录逻辑 ...
git commit -m "feat: 添加用户登录功能"
Step 3：开发后（AI 自动归档）
你: /code-documents-auto 开发完了，归档
AI: 好的，我总结一下变更...
[AI 自动执行]
1. 对比 git diff，提取变更点
2. 更新 .ai-context/changelog/2026-06-01-添加用户登录.md
3. 更新 .ai-context/modules/auth.md
4. 更新 .ai-context/api/auth.md
5. 更新 .ai-context/database/users.md
✅ 归档完成！
变更摘要：
- 新增 3 个 API 接口
- 新增 users 表
- 新增 authMiddleware 中间件
对比：v2.x vs v3.0.0
| 维度 | v2.x（脚本驱动） | v3.0.0（AI 驱动） |
|---|---|---|
| 核心逻辑 | Shell 脚本硬编码 | AI 自己决定 |
| 文件数量 | 13 个脚本 + 3 个参考文档 | 1 个 SKILL.md |
| 增量更新 | ❌ 不支持 | ✅ /docs-scan --update |
| 灵活性 | 低（脚本写死） | 高（AI 根据项目自适应） |
| 维护成本 | 高（10+ 脚本） | 低（只维护 SKILL.md） |
| AI 角色 | "按钮"（被调用） | "思考者"（主导） |
安装和使用
安装（两行命令）
# Step 1: 添加市场
/plugin marketplace add Leo-skye-taylor/code-documents-auto-skill
# Step 2: 安装插件
/plugin install code-documents-auto@code-documents-auto-skill
更新（卸载 → 清缓存 → 重装）
# 卸载旧版本
/plugin uninstall code-documents-auto@code-documents-auto-skill
# 清除缓存（可选但推荐）
rm -rf ~/.claude/plugins/cache/code-documents-auto-skill
# 重新安装最新版本
/plugin install code-documents-auto@code-documents-auto-skill
为什么敢删掉所有脚本？
答案：Claude Code 已经足够强
v2.x 的思路：
"我写 Shell 脚本，让 AI 调用脚本" → 本末倒置
v3.0.0 的思路：
"我告诉 AI 目标，AI 自己决定怎么做" → AI-Native
举例：增量更新
- v2.x：写个
scan-codebase.sh，diff对比文件，grep提取变更 → 复杂、易错 - v3.0.0：告诉 AI "只更新变更的文件"，AI 自己会
git diff、自己判断更新范围 → 简单、准确
开源初心（v3.0.0 版）
我做这个插件的初衷没变：
让开发者专注于写代码，文档管理交给 AI。
v3.0.0 是一次"激进"的重构，删掉了 6700+ 行脚本，但换来了：
- ✅ 更灵活（AI 根据项目自适应）
- ✅ 更易维护（只维护 1 个 SKILL.md）
- ✅ 更 AI-Native（AI 是思考者，不是按钮）
如果你也在探索 "AI-Native 开发工具"，欢迎交流！
资源链接
- 🔥 GitHub：github.com/Leo-skye-ta…
- 📖 README：github.com/Leo-skye-ta…
- 🐛 提 Issue：github.com/Leo-skye-ta…
- 💬 讨论区：github.com/Leo-skye-ta…
写在最后
v3.0.0 才发布几个小时，肯定还有 Bug。
欢迎提 Issue / PR，一起把 "AI-Native 文档管理" 这件事做好 🙏
如果这篇文章对你有启发，点赞 + 收藏 + 关注 是对我最大的支持 🚀
P.S.
小红书那边我也发了 v3.0.0 的推广笔记，有兴趣的可以去看看 👉 www.xiaohongshu.com/explore/6a1…
标签： #Claude #AI编程 #开源项目 #效率工具 #文档管理 #AI-Native #重构 #ClaudeCode
