| name | ai-readme |
| description | AI README 生成器 - 扫描代码并为项目生成 AI/人类共用的规则文档（AGENTS.md + .cursor/rules/ai-readme/）。当用户说 /ai-readme、@ai-readme、生成 AI 文档、生成项目规则文档、给项目加 AGENTS.md、初始化项目规则、为项目写 AI 文档时触发。 Use when this capability is needed. |
| metadata | {"author":"gabrielmoreira"} |
AI README 生成器
本 Skill 用于为项目自动生成「AI + 人类」共用的项目规则文档，全部规则与模板都内联在本文件里，不依赖任何外部 references/ 或 assets/。
目标产物结构
项目根/
├── AGENTS.md # 面向 AI Agent 的项目入口（必生成）
└── .cursor/rules/ai-readme/
├── RULE.mdc # 必读入口 + 快速导航
├── generated/ # AI 从代码扫描出的"技术事实"
│ ├── 项目结构.mdc
│ ├── 技术架构.mdc
│ ├── 开发指南.mdc
│ └── 核心流程.mdc
└── manual/ # 待人工补充的"业务知识"
├── 业务知识.mdc
└── 历史经验.mdc
核心原则
类目 谁写 原则
generated/ AI 写 只写"代码里能看到"的客观信息（结构、技术栈、命令、调用链）
manual/ 人写（AI 给模板） 业务术语、领域规则、踩坑——AI 只生成空模板，已存在则跳过
AGENTS.md AI 写 项目入口：概述 + 命令 + 边界，每次都重新生成
RULE.mdc AI 写 快速导航；每写完一份 generated/ 立即更新此文件中的状态
执行流程（按顺序执行，不要跳步）
阶段 1：扫描
- 读项目根的依赖文件，识别语言与框架：
- package.json / pnpm-lock.yaml → JS/TS
- pom.xml / build.gradle → Java
- pyproject.toml / requirements.txt → Python
- Cargo.toml → Rust
- go.mod → Go
- 用 Glob 列出 src/、app/、lib/、tests/ 等核心目录
- 抽样阅读 3~5 个核心源文件，识别分层与入口
- 检查 .cursor/rules/ai-readme/ 是否已存在产物：
- 不存在 → 全量生成
- 存在 → 增量更新（保留 manual/，重写 generated/ 与 RULE.mdc）
阶段 2：制定 todo
用 todo 工具列出 7 项任务，逐项完成：
- 写 RULE.mdc（先骨架）
- 写 generated/项目结构.mdc → 立即把 RULE.mdc 中对应行 [ ] 改为 [x]
- 写 generated/技术架构.mdc → 立即更新 RULE.mdc
- 写 generated/开发指南.mdc → 立即更新 RULE.mdc
- 写 generated/核心流程.mdc → 立即更新 RULE.mdc
- 写 manual/ 模板（已存在则跳过）
- 写项目根 AGENTS.md
阶段 3：自检
● 所有 generated/ 在 RULE.mdc 中是否都已 [x]
● 「项目结构 → 技术架构 → 核心流程」三处描述同一入口/类名是否一致
● 是否给用户列出了"需要人工补充的 TODO"清单
硬性约束
● 禁止覆盖manual/ 已存在的文件
● 禁止使用 Emoji（⚠️ 除外）
● 不要凭空捏造 API、路径、命令；不确定就标
● 每个 .mdc 文档至少包含 1 个 Mermaid 或 ASCII 图
● 每个 .mdc 文档必须有 frontmatter：description + alwaysApply: false
● 写入文件前先用 Read 工具确认文件是否存在；存在且属于 manual/ 时跳过
模板：RULE.mdc
description: "AI README 必读入口 - 项目规则导航；任何任务前先读此文件"
alwaysApply: false
AI README - 项目规则入口
项目总览
flowchart LR
A[入口] --> B[核心模块] --> C[依赖]
生成信息
- 生成时间：YYYY-MM-DD HH:mm
- 生成分支：
快速导航
AI 生成文档（generated/）
- [] 项目结构 - 目录树、模块划分；了解代码组织时使用
- [] 技术架构 - 分层架构、技术栈；了解技术选型时使用
- [] 开发指南 - 环境搭建、构建/启动命令；上手时使用
- [] 核心流程 - 主要业务调用链；理解系统时使用
人工维护文档（manual/）
模板：generated/项目结构.mdc
description: "项目结构 - 目录树、模块划分、依赖关系；当需要了解代码组织时使用"
alwaysApply: false
项目结构
目录树
项目根/
├── ...
模块职责
模块依赖关系
flowchart LR
A --> B
模板：generated/技术架构.mdc
description: "技术架构 - 分层架构和技术栈清单；当需要了解技术选型时使用"
alwaysApply: false
技术架构
架构总览
flowchart TD
UI[表现层] --> Logic[业务层] --> Data[数据层]
分层说明
技术栈
| 类目 | 技术 | 版本 | 用途 |
|---|
| 语言/运行时 | | | |
| 主框架 | | | |
| 测试框架 | | | |
| 构建工具 | | | |
模板：generated/开发指南.mdc
description: "开发指南 - 环境搭建、启动命令、配置说明；当需要设置开发环境时使用"
alwaysApply: false
开发指南
环境准备
常用命令
配置文件清单
调试与验证
模板：generated/核心流程.mdc
description: "核心流程 - 主要业务调用链；当需要理解系统运作时使用"
alwaysApply: false
核心流程
提示：以下流程由 AI 从代码推断而来，请用户确认 P0/P1 是否就是团队认知中的核心。
流程清单
流程 1：<名称>
sequenceDiagram
participant Client
participant Entry
participant Core
Client->>Entry: 请求
Entry->>Core: 调度
Core-->>Client: 响应
调用链
- <文件:类.方法>
- ...
关键分支
模板：manual/业务知识.mdc（仅在不存在时创建）
description: "业务知识 - 项目背景、领域术语、业务规则；当需要理解业务上下文时使用"
alwaysApply: false
业务知识
项目背景
领域术语
核心业务规则
模板：manual/历史经验.mdc（仅在不存在时创建）
description: "历史经验 - 踩坑记录；AI 写代码或做方案前必读"
alwaysApply: false
历史经验
AI 与新成员写代码前先看这里，避免重复踩坑。
踩坑记录
模板：项目根目录 AGENTS.md
AGENTS.md
项目概述
开发命令
关键目录
-src/ -
-tests/ -
边界约束
AI 上下文
详细规则见 .cursor/rules/ai-readme/RULE.mdc：
- 架构：
.cursor/rules/ai-readme/generated/技术架构.mdc
- 流程：
.cursor/rules/ai-readme/generated/核心流程.mdc
- 业务（人工维护）：
.cursor/rules/ai-readme/manual/业务知识.mdc
- 踩坑（人工维护）：
.cursor/rules/ai-readme/manual/历史经验.mdc
验收标准
执行完毕后，必须输出：
- 已生成文件清单（含路径、大小）
- 每份文档当前状态（[x] / [ ] / [?]）
- 需要人工补充的 TODO 清单（来自 manual/ 中的 ）
- 推荐的下一步动作（哪几处建议团队第一时间补全）
Source: gabrielmoreira/agent-skills-mirror — distributed by TomeVault.
