project-md-generator

# 项目 AI 记忆 md 文件生成与规范化指南 ## 这个 Skill 做什么 为 AI 编程 IDE（Claude Code / Codex / Cursor / Gemini 等）生成或规范化项目的"记忆 md 文件"——也就是 `CLAUDE.md`、`AGENTS.md` 这类让 AI 在每次会话开头自动读取、用来理解项目约定与上下文的文件。 它解决两类需求： - **从零生成**：新项目或老项目从没有这类文件，AI 每次都得重新摸索项目约定； - **规范化**：项目里已经有零散、过时、口径不一的 md 文件，需要按统一标准重写合并。 > 为什么重要：AI 每次会话开头都会读这个文件，它就是"项目长期记忆"。写得好，AI 一次就懂约定、少犯重复错误；写得差或没有，AI 会反复发明轮子、踩同样的坑。所以这个文件的目标不是"写得多"，而是"让 AI 用最低的成本记住最关键的事"。 ## 核心原则（动手前先记住） 这些原则来自 `CLAUDE.md` / `AGENTS.md` 的公开最佳实践，详见 [best-practices.md](references/best-practices.md)。生成任何 md 文件都要贯彻： 1. **高信噪比、宁短勿长**：AI 每次会话都要全文读这个文件，越长越费上下文、越容易被忽略。根目录 md 硬上限 **160 行**，分层 md 硬上限 **100 行**。超长内容下沉到 `docs/` 并在 md 里留链接。 2. **事实优先，禁止编造**：常用命令、包结构、技术栈必须来自项目实际文件（`pom.xml` / `package.json` / 目录树 / 构建脚本）。命令先核对真实来源；非启动型检查可执行验证，dev/watch、服务、模拟器、真机、HBuilderX 和开发者工具必须先询问用户，未经运行不得写成“已实测”。 3. **最重要的放最前**：AI 顺序阅读，靠前的规则关注度更高。把"AI 最容易犯错、最该先知道的事"放在文件顶部。 4. **写 why，不只是 what**：每条约束附带"为什么"，AI 才能在没覆盖到的场景做出正确判断，而不是死记硬背。 5. **不重复，靠链接**：详细规范不要塞进根 md，指向已有文档（如公司 [framework.md](../lingman-core/framework.md)、前端规范、`docs/`）。 6. **长期知识，不是临时指令**：只写跨会话稳定成立的内容；临时性的（如"今天先改登录页"）不写进来。 ## 何时生成分层 md（"庞大项目"判定） 只有**庞大项目**才在各分层目录补充分层说明 md；中小项目只生成根目录 md 一个文件即可。判定信号（满足任一即视为庞大）： - 多模块 Maven 工程（根 `pom` 下有多个 `*-api` / `*-biz` 子模块） - 前后端单体仓库或 workspace/monorepo（同时含 Vue/uni-app 前端与 Spring Boot 后端，或含多个独立应用） - APP 优先的 uni-app 工程存在页面、请求、Store、TabBar、跨端媒体等多个高约束子系统 - 单模块但分层目录文件数很多（如 `controller/`、`service/` 下各有十几个业务包） - 多人协作、新人频繁接手的项目 > 判定不确定时**询问用户**："这个项目体量较大，是否需要在各分层目录（controller / service / 前端 views 等）各放一个说明 md？"由用户拍板。不要默认对所有项目都铺一堆分层 md——那只会制造维护负担。 ## 文件命名（多 IDE 兼容） 不同 IDE 读取的文件名不同，常见映射： | IDE / 工具 | 文件名 | |------------|--------| | Claude Code | `CLAUDE.md` | | OpenAI Codex | `AGENTS.md` | | Cursor | `AGENTS.md`（或 `.cursor/rules/`） | | Gemini | `GEMINI.md` | | 通用 / 多 IDE | `AGENTS.md`（厂商中立标准，多数工具都认） | **默认行为**：先问用户主要用哪个 IDE；不确定时生成 `AGENTS.md`（兼容性最广）。若用户同时用 Claude Code + Codex，可生成 `CLAUDE.md` + `AGENTS.md` 两份、内容一致。 分层 md 的文件名**与根 md 保持一致**（根是 `AGENTS.md` 则分层也用 `AGENTS.md`），这样 IDE 进入子目录时会自动加载对应分层文件——这正是"渐进式披露"的机制。 ## 工作流程 ### Step 0 — 判断场景 | 场景 | 用户信号 | 处理 | |------|----------|------| | **A 全新生成** | "/init"、"初始化项目"、"生成 CLAUDE.md/AGENTS.md"、新项目 | 从模板生成根 md（庞大项目再加分层 md） | | **B 规范化现有** | "整理/规范化/重写项目的 md"、"这些 md 太乱了" | 先读全部现有 md，提取有效信息，按模板重写合并 | | **C 首次接触无 md** | "第一次接触这个项目"、"帮我熟悉项目"，且项目无任何 AI 记忆 md | 同 A，但更侧重把"新人最需要先知道的"放进 md | ### Step 1 — 探测项目（事实采集） 动手写之前先用工具读取以下信息，**禁止凭空编造**： - 构建配置：`pom.xml`（Maven 坐标、模块、Java 版本）、`package.json`（scripts、`packageManager`、依赖与框架版本） - 目录结构：用 Glob / ls 看顶层目录、workspace/monorepo 边界与分层包结构（`src/main/java/com/lm/app/...`、前端 `src/`） - 构建脚本/工具：`mvnw`、实际锁文件、npm/pnpm/yarn workspace、`lingman.config.json`、`Dockerfile` - uni-app 证据（如存在）：`@dcloudio/*`、`src/App.vue`、`uni.scss`、`pages.config.*`、页面 `definePage()`、`manifest.config.*`、生成的 pages/manifest JSON、`uno.config.*`、`env/` 或 `.env*` - uni-app 关键架构（如存在）：自动 API 目录及生成命令、HTTP 请求桥接与认证、Pinia Store、TabBar、条件编译、跨端视频/媒体组件及资源清理位置 - 现有 md（场景 B）：找出所有 `*.md`、`CLAUDE.md`、`AGENTS.md`、`.cursorrules`，逐个读 - 敏感配置只记录“文件位置、用途和维护方式”，不得复制环境地址中的凭据、密码、Token、AppID、证书、签名或私有响应内容 锁文件、`packageManager` 和 workspace 配置冲突时，只记录已确认事实并要求维护者决定，不擅自切换包管理器、删除锁文件或制造第二种锁文件。把采集到的事实记录下来，作为填充模板的依据。 ### Step 2 — 判断是否庞大项目（见上节），决定是否生成分层 md ### Step 3 — 生成根目录 md 文件 1. **严格套用模板**：使用 [root-template.md](references/root-template.md) 的章节顺序与标题，不自创章节顺序。 2. **逐字复制的段落**（公司全员一致，禁止改写）： - `## 开发约束` 下的"公司 skill 规范"条目 + "日志要求"条目 - `## 维护触发条件` 整段 这两段在所有项目里必须**一字不差**，直接从模板复制，不要"优化"措辞。 3. **填充项目相关段落**：`项目概述与技术栈`、`常用命令`、`包结构与分层`、`注意事项`、`避坑指南` 用 Step 1 采集的真实信息填写。 4. **命令验证分级**：`## 常用命令` 中每条命令都必须来自真实 script、wrapper 或项目文档，并标注验证等级： - **来源已核对**：只确认命令真实存在，尚未执行； - **静态检查已通过**：typecheck、lint 等一次性非启动命令已执行； - **运行已验证**：dev server、后端、模拟器、真机或外部工具在用户明确同意后实际运行。 启动类命令未经同意不得执行，也不得写成“可用”或“已验证”；缺少 SDK、证书或平台环境时如实说明。 5. **行数控制**：根 md ≤ 160 行。某节内容超过约 10 行就下沉到 `docs/` 并在本文件留链接（这条本身已写进"维护触发条件"）。 ### Step 4 —（仅庞大项目）生成分层 md 参照 [layer-guide.md](references/layer-guide.md)： - **放置位置**（示例）： - 后端 SpringBoot：`src/main/java/com/lm/app/controller/`、`.../service/`、`.../convert/`、`.../models/` 等分层目录各一个 md - 管理后台 Vue：`src/views/`、`src/components/`、`src/api/`、`src/store/`（或 `pinia`）等各一个 md - uni-app：按真实职责选择 `src/pages/`、`src/components/`、自动 API 外层接入目录、请求层、Store、TabBar、跨端媒体目录；不在生成目录中放维护说明 - **结构自由**：分层 md **不套用根模板**，按该层特点组织（本层职责 / 关键文件 / 约定 / 常见坑 / 入口）。 - **行数**：每个分层 md ≤ 100 行，超长同样下沉到更细的 `docs/`。 - **内容聚焦该层**：只写"在这一层工作才需要知道的事"，避免与根 md 重复。 ### Step 5 — 输出清单与维护提示 生成完毕后向用户列出： - 已生成/改写的所有 md 文件路径（根 + 各分层） - 提示根 md 的"维护触发条件"——后续项目结构、命令、约束变化时要同步更新 - 若有内容下沉到 `docs/`，列出对应链接 ## 硬性约束（生成时逐条自查） - [ ] 根 md ≤ 160 行；分层 md ≤ 100 行 - [ ] `## 开发约束`（skill 规范 + 日志要求）、`## 维护触发条件` 与模板**逐字一致** - [ ] 常用命令来自真实文件并标注“来源已核对 / 静态检查已通过 / 运行已验证”，未把未执行命令写成已验证 - [ ] dev/watch、服务、模拟器、真机、HBuilderX 和开发者工具均未在用户同意前启动 - [ ] 技术栈、包结构、workspace、包管理器和锁文件来自真实文件，冲突没有被擅自修复 - [ ] uni-app 项目已记录真实页面/manifest 配置源、自动 API、请求/Store/TabBar/条件编译等关键入口，但未把生成物当主要编辑源 - [ ] 未复制环境凭据、密码、Token、AppID、证书、签名或其他敏感值 - [ ] 庞大项目才生成分层 md，且分层 md 不套根模板 - [ ] 没有编造的项目信息；不确定的部分标注“待补充”并询问用户，而不是瞎填 ## 参考文档 | 场景 | 文档 | |------|------| | 根目录 md 完整模板（含逐字段落） | [root-template.md](references/root-template.md) | | 分层 md 放置位置、结构、示例（Spring Boot / 管理后台 Vue / uni-app） | [layer-guide.md](references/layer-guide.md) | | CLAUDE.md / AGENTS.md 最佳实践详解 | [best-practices.md](references/best-practices.md) | | 公司后端框架规范（生成 md 时可作为外链引用） | [framework.md](../lingman-core/framework.md) | | uni-app 通用规范（移动端项目可作为外链引用） | [uni-app-spec.md](../lingman-core/uni-app/uni-app-spec.md) |