docs

README 生成器

生成或更新面向产品负责人的 README.md，使用法语撰写，简洁明了，并配有 Mermaid 图表。审查并改进 docs/ 目录中的所有技术文档。如果 CLAUDE.md 和 AGENT.md 不存在，也会生成这两个文件。

---

适用场景

• 项目根目录中不存在 README.md
• 重大变更后，现有 README.md 已过时
• 添加重要功能或进行架构变更后
• 为产品负责人或新项目干系人介绍项目

---

工作内容

第 1 步：探索代码库

全面探索项目，了解其用途、架构和技术栈：

• 包清单文件： 阅读根目录和子包（monorepo）中的 package.json、composer.json、pyproject.toml、Cargo.toml 或同类文件
• 项目结构： 列出顶层目录和关键文件，以了解架构
• 文档： 检查是否存在 docs/ 目录。阅读 docs/ 中每个 .md 文件的前 20-30 行，为每个文件提炼一条简短的法语描述，用于目录
• CI/CD： 查找 .github/workflows/、.gitlab-ci.yml、Jenkinsfile、Dockerfile、docker-compose.yml
• 数据库： 查找迁移文件、模式定义以及 Prisma/TypeORM/Sequelize 配置
• 路由/控制器： 扫描路由定义、API 端点和控制器
• Git 信息： 运行 git log --oneline -10 和 git remote -v，了解近期活动和托管情况
• 环境： 查找 .env.example 和环境配置文件

第 2 步：创建或更新

• 检查项目根目录中是否存在 README.md
• 如果不存在： 使用下方模板从头创建
• 如果存在： 阅读现有内容，更新事实性部分（技术栈、架构、功能），并保留团队添加的自定义部分

第 3 步：生成内容

遵循下方“README 模板”部分定义的模板。所有内容都必须使用法语，并遵循写作指南。

第 4 步：写入文件

将 README.md 保存到项目根目录。

第 5 步：生成 CLAUDE.md 和 AGENT.md

仅当项目根目录中不存在这些文件时。 如果文件已存在，则不要修改。

• CLAUDE.md — 根据代码库探索结果，为 Claude Code 生成指令（请参阅下方专门章节）
• AGENT.md — 根据代码库探索结果，为自主 AI Agent 生成指令（请参阅下方专门章节）

第 6 步：审查技术文档

审查 docs/ 目录中的每个 .md 文件，并依据下方定义的文档质量规则提出改进建议。

对于每个文件：

1. 阅读全文
2. 根据“文档质量规则”部分中的每条规则进行评估
3. 提出具体改进——重写违反规则的章节
4. 直接在文件中应用更改
5. 向用户汇报每个文件的更改摘要

不要删除或移除现有文档文件。 只改进其内容。

第 7 步：识别缺失的文档

将代码库探索结果（第 1 步）与现有的 docs/ 文件交叉对照，找出未记录的重要或关键功能。

1. 盘点已有文档主题 — 列出每个 docs/*.md 文件涵盖的内容
2. 盘点代码库功能 — 根据第 1 步，列出代码中发现的关键功能、模块、API、集成、工作流和架构决策
3. 分析差距 — 对比两份清单。标记符合以下任一条件的功能：
   • 在生产代码中使用，但没有对应的文档
   • 属于核心业务工作流（例如，身份验证、数据管道、外部集成）
   • 属于架构决策，新团队成员若不了解背景就会感到困惑
   • 属于行为不明显的复杂模块
4. 提出新文档文件 — 针对每项差距，向用户提供：
   • 建议的文件名（例如，docs/authentication-flow.md）
   • 对文件内容的一句话说明
   • 优先级：关键（妨碍理解系统）或 重要（能显著帮助新成员熟悉项目）
5. 询问用户要创建哪些建议文件
6. 生成获批的文件，遵循文档质量规则——使用法语、内容简洁、面向产品负责人（PO），并在适用时使用 Mermaid 图表

第 8 步：确认

向用户总结已完成的工作：

• 哪些文件是新建的，哪些文件是更新的
• 包含的主要章节
• 哪些信息无法确定，因此保留为占位内容
• **文档审查：**列出已审查的 docs/ 文件，并用一句话概述每个文件所做的改进
• **缺失文档：**列出建议新增的文档文件，以及哪些文件已获批并创建

---

README 模板

生成的 README.md 必须遵循以下结构：

# [Project Name]

简短介绍（1-2 句话，非技术性）。说明产品的用途及目标用户。

## 目录

自动生成目录，列出 README 的所有章节并附上锚点链接。包含一个技术文档子章节：

## Table des matières

- [À quoi sert ce produit ?](#à-quoi-sert-ce-produit-)
- [Fonctionnalités principales](#fonctionnalités-principales)
- [Comment ça fonctionne](#comment-ça-fonctionne)
- [Environnements](#environnements)
- [Déploiement](#déploiement)
- [Stack technique](#stack-technique)
- [Documentation complémentaire](#documentation-complémentaire)

### Documentation technique

| Document | Description |
|----------|-------------|
| [Architecture REST & WebSocket](docs/REST-WebSocket-Architecture.md) | Description de l'architecture API |
| [Schéma de base de données](docs/database-schema.md) | Structure des tables et relations |

**重要：**每个文档文件的描述都必须根据实际阅读文件内容得出（第 1 步），不得凭空编造。

## 这个产品有什么用？

说明产品的业务价值。用 3-5 个要点，从用户角度描述产品能提供什么。

## 主要功能

列出面向用户价值的功能。使用项目符号列表，重点说明用户可以做什么，而不是功能的实现方式。

## 工作原理

使用 Mermaid graph LR 或 graph TD 绘制高层架构图，随后附上简短的文字说明。

```mermaid
graph LR
    A[Utilisateur] --> B[Application Web]
    B --> C[API Backend]
    C --> D[Base de données]
    C --> E[Services externes]
`` `

L'utilisateur interagit avec l'application web, qui communique avec l'API backend. Le backend gère la logique métier et stocke les données en base.

## 环境

使用表格列出环境信息：

| Environnement | URL | Description |
|---------------|-----|-------------|
| Développement | `http://localhost:3000` | Environnement local |
| Staging | `https://staging.example.com` | Pré-production |
| Production | `https://app.example.com` | Environnement de production |

如果在配置中找到实际 URL，请使用实际 URL；否则使用合理的占位内容。

## 部署

使用 Mermaid graph LR 绘制 CI/CD 管道图，随后附上简短说明。

## 技术栈

按类别列出技术栈，分为 3-5 行：

- **Frontend :** React, TypeScript, TailwindCSS
- **Backend :** Node.js, NestJS, TypeORM
- **Base de données :** PostgreSQL
- **Hébergement :** Docker, GitLab CI/CD

## 补充文档

如果 docs/ 文件存在，则添加指向这些文件的链接。如果不存在 docs/ 文件夹，则省略此章节。

---

Mermaid 图表规则

1. 使用法语标签 — 所有节点标签和边标签都必须使用法语
2. 每张图最多包含 8-10 个节点 — 保持图表清晰易读，突出高层信息
3. 允许的类型：graph、flowchart、sequenceDiagram
4. 禁止的类型：classDiagram、erDiagram、stateDiagram（对产品负责人而言过于技术化）
5. 每张图下方都要有文字说明 — 不能只放图表
6. 保持简单明了 — 避免使用嵌套子图、复杂条件或技术细节

Mermaid 图表示例

graph LR
    A[Développeur] -->|Push du code| B[GitLab CI]
    B -->|Tests auto| C{Tests OK ?}
    C -->|Oui| D[Déploiement Staging]
    C -->|Non| E[Notification erreur]
    D -->|Validation manuelle| F[Déploiement Production]

该图展示了持续部署管道。当开发者推送代码时，自动测试随即启动。如果测试通过，代码会部署到 staging 环境；经过人工验证后，再部署到生产环境。

---

法语写作指南

• 使用自然、专业的法语，统一使用“vous”（敬语）
• 避免使用英语借词，但没有法语对应说法的技术术语除外（WebSocket、Docker、CI/CD、API 等）
• **使用短句：**每句最多 20 个词
• 优先使用项目符号列表，避免长段落
• 避免使用技术术语——面向产品负责人写作，而非开发者
• README 中不使用代码块（Mermaid 图除外）
• 首次出现时解释缩略语（例如：“CI/CD（持续集成与持续部署）”）
• 全文术语保持一致

---

文档质量规则

审核和改进 docs/ 中的文件时，须遵循以下规则。每个文档文件都必须符合这些要求。

语言

• 使用法语撰写——所有内容都必须使用法语
• **例外：**没有法语对应说法的技术术语（API、WebSocket、Docker、CI/CD、JSON 等）保留英文
• 使用敬语——始终使用“vous”
• 首次出现时解释缩略语

简洁

• 使用短句——每句最多 20 个词
• 优先使用项目符号列表，而非段落——长篇内容优先采用结构化列表
• 避免填充内容——删除“在本节中，我们将介绍……”之类的引言，直接说明要点
• 每段只表达一个观点——如果一段涉及两个主题，请拆分段落

可读性

• 采用便于浏览的结构——灵活使用 H2、H3 标题，让读者快速找到所需内容
• 在每个章节中首次提及时，将关键术语加粗
• 使用表格进行比较——比较选项、功能或配置时，用表格代替文字描述
• 代码示例应简短且聚焦——每个代码块最多 10-15 行，并附上一行注释说明用途

受众

• 默认面向产品负责人——先解释“是什么”和“为什么”，再解释“如何实现”
• 主题需要时提供技术细节——解析器、协议、数据库架构和 API 契约可以且应该包含技术细节
• 清楚标注技术章节——使用标题或提示框（例如：“> 技术细节”），方便非技术读者跳过

Mermaid 图表

• 优先用图表代替冗长描述——如果概念涉及流程、时序或架构，请使用 Mermaid 代替或补充文字说明
• 遵循上文定义的 Mermaid 图表规则（法语标签、最多 8-10 个节点、允许的类型，并在下方提供文字说明）
• 替换冗长说明——如果某个章节用 5 行以上的内容描述流程或架构，请考虑使用图表替代或补充说明

结构

• 每个文档文件都必须以 H1 标题开头，标题须与文件名或主题相符
• 标题后紧跟一段简短的介绍（1-2 句），说明文档涵盖的内容及目标读者
• **章节顺序应符合逻辑：**背景/目的 → 工作原理 → 详情/参考 → 示例

---

创建模式与更新模式

创建模式（不存在现有 README.md）

根据代码库探索结果，从头生成所有章节。

更新模式（README.md 已存在）

1. 阅读现有 README.md
2. 确定哪些章节与模板相符
3. 根据当前代码库状态更新事实性内容（技术栈、架构、功能、环境）
4. 保留与模板不符的自定义章节——这些章节可能是团队手动添加的
5. 更新目录，使其反映所有章节

CLAUDE.md 生成

仅当项目根目录中不存在 CLAUDE.md 时才生成。

探索代码库，推断并纳入以下内容：

• 项目概述： 用一段话总结项目是什么
• 技术栈和关键依赖项及其版本
• 项目结构： 关键目录及其用途
• 实用命令： 开发、构建、测试、代码检查、迁移、数据填充——使用在 package.json 脚本或 Makefile 中找到的实际命令
• 代码约定： 命名模式、文件结构模式、观察到的架构模式（例如 React hooks、服务模式、控制器与路由分离）
• Git 工作流： 分支命名约定（如可观察到）、提交消息模式（根据 git log）
• Claude 应了解的关键文件和目录
• 项目特有的注意事项和重要信息（例如 monorepo 结构、共享包、所需环境变量）
• 编写新代码时应遵循的模式（根据现有代码风格推断）

---

AGENT.md 生成

仅当项目根目录中不存在 AGENT.md 时才生成。

探索代码库，推断并纳入以下内容：

• 项目摘要和目标（2-3 句话）
• Monorepo 结构和包之间的依赖关系（如适用）
• 必要命令： 安装、开发、构建、测试、迁移、数据填充——使用实际命令
• 进行自动化修改时应遵守的代码约定
• 开发工作流： 分支、提交、CI/CD 流水线
• 自动化修改的重要注意事项： 应避免的事项、必须执行的事项、不得修改的关键文件

---

示例输出

以下是预期 README 格式的精简示例：

# Overwatch

Plateforme de supervision applicative permettant de surveiller la santé et les performances de vos applications en temps réel.

## Table des matières

- [À quoi sert ce produit ?](#à-quoi-sert-ce-produit-)
- [Fonctionnalités principales](#fonctionnalités-principales)
- [Comment ça fonctionne](#comment-ça-fonctionne)
- [Environnements](#environnements)
- [Déploiement](#déploiement)
- [Stack technique](#stack-technique)
- [Documentation complémentaire](#documentation-complémentaire)

### Documentation technique

| Document | Description |
|----------|-------------|
| [Architecture API](docs/api-architecture.md) | Vue d'ensemble de l'architecture REST |

## À quoi sert ce produit ?

- Surveiller la disponibilité de vos applications en continu
- Recevoir des alertes en cas de dysfonctionnement
- Visualiser l'historique de santé via des tableaux de bord
- Gérer les environnements de déploiement (dev, staging, production)
- Centraliser la supervision de toutes vos applications

## Fonctionnalités principales

- **Tableau de bord temps réel** — Vue d'ensemble de la santé de toutes vos applications
- **Historique de santé** — Graphiques et métriques sur les performances passées
- **Gestion multi-environnements** — Suivi par environnement de déploiement
- **Alertes automatiques** — Notification en cas de dégradation du service

## Comment ça fonctionne

` ``mermaid
graph LR
    A[Utilisateur] --> B[Interface Web]
    B --> C[API NestJS]
    C --> D[Base PostgreSQL]
    C --> E[Vérification de santé]
    E --> F[Applications surveillées]
` ``

L'utilisateur accède à l'interface web pour consulter l'état de ses applications. L'API backend effectue des vérifications de santé régulières et stocke les résultats en base de données.

## Stack technique

- **Frontend :** React 18, TypeScript, TailwindCSS
- **Backend :** NestJS, TypeORM, PostgreSQL
- **Infrastructure :** Docker, GitLab CI/CD

---

检查清单

保存 README.md 前，请确认：

• 所有内容均为法语（技术术语除外）
• 目录涵盖所有章节，且锚点链接正确
• 技术文档子章节列出所有 docs/*.md 文件，并根据内容推断其描述
• Mermaid 图表有效，且节点数不超过 8-10 个
• Mermaid 图表仅使用允许的类型（graph、flowchart、sequenceDiagram）
• 每个图表下方都有文字说明
• Mermaid 图表中的标签为法语
• 不包含代码块（Mermaid 除外）
• 每句话少于 20 个单词
• 始终使用敬语
• 首次出现时解释缩略语
• 仅在文件不存在时生成 CLAUDE.md
• 依据文档质量规则检查所有 docs/*.md 文件
• 文档使用法语，简洁、便于浏览，并以产品负责人为导向
• 在可以替代冗长说明的地方添加 Mermaid 图表
• 完成差距分析：对比代码库功能与现有文档
• 创建前先向用户提出缺失的关键/重要文档
• 新文档文件遵循文档质量规则
• 告知用户创建/更新了哪些内容、改进了哪些文档，以及提出/创建了哪些新文档