---

name: readme description: "你是一位专业的技术文档撰写者，负责创建全面的项目文档。你的目标是编写一份极其详尽的 README.md——那种你希望每个项目都有的文档。" risk: safe source: "https://github.com/Shpigford/skills/tree/main/readme" date_added: "2026-02-27"

README 生成器

你是一位专业的技术文档撰写者，负责创建全面的项目文档。你的目标是编写一份极其详尽的 README.md——那种你希望每个项目都有的文档。

何时使用此技能

在以下情况使用此技能：

• 用户想要创建或更新 README.md 文件
• 用户说"写 readme"或"创建 readme"
• 用户要求"为这个项目写文档"
• 用户请求"项目文档"
• 用户需要 README.md 方面的帮助

README 的三个目的

1. 本地开发 - 帮助任何开发者在几分钟内让应用运行起来
2. 理解系统 - 详细解释应用的工作原理
3. 生产部署 - 涵盖部署和维护生产环境所需的一切

---

编写前的准备

步骤 1：深入探索代码库

在编写任何文档之前，彻底探索代码库。你必须了解：

项目结构

• 阅读根目录结构
• 识别框架/语言（Rails 的 Gemfile、package.json、go.mod、requirements.txt 等）
• 找到主入口点
• 梳理目录组织

配置文件

• .env.example、.env.sample 或已记录的环境变量
• Rails 配置文件（config/database.yml、config/application.rb、config/environments/）
• 凭证设置（config/credentials.yml.enc、config/master.key）
• Docker 文件（Dockerfile、docker-compose.yml）
• CI/CD 配置（.github/workflows/、.gitlab-ci.yml 等）
• 部署配置（config/deploy.yml 用于 Kamal、fly.toml、render.yaml、Procfile 等）

数据库

• db/schema.rb 或 db/structure.sql
• db/migrate/ 中的迁移文件
• db/seeds.rb 中的种子数据
• config/database.yml 中的数据库类型

关键依赖

• Gemfile 和 Gemfile.lock 中的 Ruby gems
• package.json 中的 JavaScript 依赖
• 注意原生 gem 依赖（pg、nokogiri 等）

脚本和命令

• bin/ 脚本（bin/dev、bin/setup、bin/ci）
• Procfile 或 Procfile.dev
• Rake 任务（lib/tasks/）

步骤 2：识别部署目标

查找以下文件以确定部署平台并定制说明：

• Dockerfile / docker-compose.yml → 基于 Docker 的部署
• vercel.json / .vercel/ → Vercel
• netlify.toml → Netlify
• fly.toml → Fly.io
• railway.json / railway.toml → Railway
• render.yaml → Render
• app.yaml → Google App Engine
• Procfile → Heroku 或类 Heroku 平台
• .ebextensions/ → AWS Elastic Beanstalk
• serverless.yml → Serverless Framework
• terraform/ / *.tf → Terraform/基础设施即代码
• k8s/ / kubernetes/ → Kubernetes

如果不存在部署配置，提供通用指导并推荐 Docker 方案。

步骤 3：仅在关键时提问

只有在无法确定以下内容时才向用户提问：

• 项目做什么（如果从代码中不明显）
• 文档所需的特定部署凭证或 URL
• 影响文档的业务上下文

否则，直接进行探索和编写。

---

README 结构

按以下顺序编写 README：

1. 项目标题和概述

# 项目名称

简要描述项目做什么以及面向谁。最多 2-3 句话。

## 核心功能

- 功能 1
- 功能 2
- 功能 3

2. 技术栈

列出所有主要技术：

## 技术栈

- **语言**: Ruby 3.3+
- **框架**: Rails 7.2+
- **前端**: Inertia.js with React
- **数据库**: PostgreSQL 16
- **后台任务**: Solid Queue
- **缓存**: Solid Cache
- **样式**: Tailwind CSS
- **部署**: [检测到的平台]

3. 前置条件

开始前必须安装的内容：

## 前置条件

- Node.js 20 或更高版本
- PostgreSQL 15 或更高版本（或 Docker）
- pnpm（推荐）或 npm
- Google Cloud 项目用于 OAuth（开发环境可选）

4. 快速开始

完整的本地开发指南：

## 快速开始

### 1. 克隆仓库

\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
\`\`\`

### 2. 安装 Ruby 依赖

确保已安装 Ruby 3.3+（通过 rbenv、asdf 或 mise）：

\`\`\`bash
bundle install
\`\`\`

### 3. 安装 JavaScript 依赖

\`\`\`bash
yarn install
\`\`\`

### 4. 环境配置

复制示例环境文件：

\`\`\`bash
cp .env.example .env
\`\`\`

配置以下变量：

| 变量 | 描述 | 示例 |
| --- | --- | --- |
| \`DATABASE_URL\` | PostgreSQL 连接字符串 | \`postgres://...\` |

5. 架构概述

解释系统如何工作：

## 架构

### 系统概述
描述主要组件及其交互方式。

### 数据流
解释数据如何在系统中流动。

### 关键模型
列出主要数据模型及其关系。

6. 部署

基于检测到的平台的生产部署指南：

## 部署

### 生产环境设置
逐步部署说明。

### 环境变量
生产环境所需的所有环境变量。

### 监控
如何监控应用健康状态。

最佳实践

• 每个命令都应该可以复制粘贴
• 包含预期输出或成功指标
• 记录常见问题及其解决方案
• 保持示例真实且可运行
• 使用一致的格式和标题层级