名称: readme 描述: “当用户想要为项目创建或更新README.md文件时使用。也适用于当用户说’写readme’、‘创建readme’、‘记录这个项目’、'项目文档’或请求帮助README.md时。这个技能创建极其详尽的文档，覆盖本地设置、架构和部署。” 来源: “https://github.com/Shpigford/skills/tree/main/readme” 风险: 安全许可证: MIT 元数据: 版本: “1.0.0” 域: 架构触发词: README, 文档, 项目文档, 写readme, 创建readme 角色: 专家范围: 实施输出格式: 代码

README生成器

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

何时使用此技能

使用此技能当：

用户想要创建或更新README.md文件
用户说"写readme"或"创建readme"
用户要求"记录这个项目"
用户请求"项目文档"
用户请求帮助README.md

README的三个目的

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

写作前

步骤1：深度代码库探索

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

项目结构

阅读根目录结构
识别框架/语言（Gemfile for Rails, 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 for 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）：

bundle install

3. 安装 JavaScript 依赖

yarn install

4. 环境设置

复制示例环境文件：

cp .env.example .env

配置以下变量：

变量	描述	示例
`DATABASE_URL`	PostgreSQL 连接字符串	`postgresql://localhost/myapp_development`
`REDIS_URL`	Redis 连接（如果使用）	`redis://localhost:6379/0`
`SECRET_KEY_BASE`	Rails 密钥	`bin/rails secret`
`RAILS_MASTER_KEY`	用于凭据加密	检查 `config/master.key`

5. 数据库设置

启动 PostgreSQL（如果使用 Docker）：

docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16

创建和设置数据库：

bin/rails db:setup

这会运行 db:create, db:schema:load, 和 db:seed。

对于现有数据库，运行迁移：

bin/rails db:migrate

6. 启动开发服务器

使用 Foreman/Overmind（推荐，运行 Rails + Vite）：

bin/dev

或手动：

# 终端1: Rails 服务器
bin/rails server

# 终端2: Vite 开发服务器（用于 Inertia/React）
bin/vite dev

在浏览器中打开 http://localhost:3000。


包含每一步。假设读者在全新机器上设置。

### 5. 架构概述

这里深入细节：

```markdown
## 架构

### 目录结构

├── app/ │ ├── controllers/ # Rails 控制器 │ │ ├── concerns/ # 共享控制器模块 │ │ └── api/ # API 特定控制器 │ ├── models/ # ActiveRecord 模型 │ │ └── concerns/ # 共享模型模块 │ ├── jobs/ # 后台作业（Solid Queue） │ ├── mailers/ # 邮件模板 │ ├── views/ # Rails 视图（Inertia 下最小） │ └── frontend/ # Inertia.js React 组件 │ ├── components/ # 可重用 UI 组件 │ ├── layouts/ # 页面布局 │ ├── pages/ # Inertia 页面组件 │ └── lib/ # 前端工具 ├── config/ │ ├── routes.rb # 路由定义 │ ├── database.yml # 数据库配置 │ └── initializers/ # 应用初始化器 ├── db/ │ ├── migrate/ # 数据库迁移 │ ├── schema.rb # 当前模式 │ └── seeds.rb # 种子数据 ├── lib/ │ └── tasks/ # 自定义 Rake 任务 └── public/ # 静态资源


### 请求生命周期

1. 请求命中 Rails 路由（`config/routes.rb`）
2. 中间件栈处理请求（认证、会话等）
3. 控制器操作执行
4. 模型通过 ActiveRecord 与 PostgreSQL 交互
5. Inertia 使用属性渲染 React 组件
6. 响应发送到浏览器

### 数据流

用户操作 → React 组件 → Inertia 访问 → Rails 控制器 → ActiveRecord → PostgreSQL ↓ React 属性 ← Inertia 响应 ←


### 关键组件

**认证**

- Devise/Rodauth 用于用户认证
- 基于会话的认证与加密 cookie
- 保护路由的 `authenticate_user!` before_action

**Inertia.js 集成（`app/frontend/`）**

- React 组件从 Rails 控制器接收属性
- 控制器中的 `inertia_render` 传递数据到前端
- 通过 `inertia_share` 共享数据用于布局属性

**后台作业（`app/jobs/`）**

- Solid Queue 用于作业处理
- 作业存储在 PostgreSQL（无需 Redis）
- 监控面板在 `/jobs`

**数据库（`app/models/`）**

- 带关联的 ActiveRecord 模型
- 复杂查询的查询对象
- 共享模型行为的 Concerns

### 数据库模式

users ├── id (bigint, PK) ├── email (string, 唯一, 非空) ├── encrypted_password (string) ├── name (string) ├── created_at (datetime) └── updated_at (datetime)

posts ├── id (bigint, PK) ├── title (string, 非空) ├── content (text) ├── published (boolean, 默认: false) ├── user_id (bigint, FK → users) ├── created_at (datetime) └── updated_at (datetime)

solid_queue_jobs（后台作业） ├── id (bigint, PK) ├── queue_name (string) ├── class_name (string) ├── arguments (json) ├── scheduled_at (datetime) └── …

6. 环境变量

所有环境变量的完整参考：

## 环境变量

### 必填

| 变量            | 描述                       | 如何获取                           |
| --------------- | -------------------------- | ---------------------------------- |
| `DATABASE_URL`  | PostgreSQL 连接字符串      | 您的数据库提供商                   |
| `SECRET_KEY_BASE` | Rails 会话/cookie 密钥     | 运行 `bin/rails secret`           |
| `RAILS_MASTER_KEY` | 解密凭据文件               | 检查 `config/master.key`（不在git中） |

### 可选

| 变量              | 描述                                       | 默认                       |
| ----------------- | ------------------------------------------ | -------------------------- |
| `REDIS_URL`       | Redis 连接字符串（用于缓存/ActionCable）   | -                          |
| `RAILS_LOG_LEVEL` | 日志详细程度                               | `debug`（开发）, `info`（生产） |
| `RAILS_MAX_THREADS` | Puma 线程数                              | `5`                        |
| `WEB_CONCURRENCY` | Puma 工作进程数                           | `2`                        |
| `SMTP_ADDRESS`    | 邮件服务器主机名                           | -                          |
| `SMTP_PORT`       | 邮件服务器端口                             | `587`                      |

### Rails 凭据

敏感值应存储在 Rails 加密凭据中：

```bash
# 编辑凭据（在 $EDITOR 中打开）
bin/rails credentials:edit

# 或用于环境特定凭据
RAILS_ENV=production bin/rails credentials:edit

凭据文件结构：

secret_key_base: xxx
stripe:
public_key: pk_xxx
secret_key: sk_xxx
google:
client_id: xxx
client_secret: xxx

在代码中访问：Rails.application.credentials.stripe[:secret_key]

环境特定

开发

DATABASE_URL=postgresql://localhost/myapp_development
REDIS_URL=redis://localhost:6379/0

生产

DATABASE_URL=<生产连接字符串>
RAILS_ENV=production
RAILS_SERVE_STATIC_FILES=true


### 7. 可用脚本

```markdown
## 可用脚本

| 命令                    | 描述                                       |
| ----------------------- | ------------------------------------------ |
| `bin/dev`               | 启动开发服务器（Rails + Vite via Foreman） |
| `bin/rails server`      | 仅启动 Rails 服务器                        |
| `bin/vite dev`          | 仅启动 Vite 开发服务器                     |
| `bin/rails console`     | 打开 Rails 控制台（加载了应用的 IRB）      |
| `bin/rails db:migrate`  | 运行待处理数据库迁移                       |
| `bin/rails db:rollback` | 回滚最后一次迁移                           |
| `bin/rails db:seed`     | 运行数据库种子                             |
| `bin/rails db:reset`    | 删除、创建、迁移和种子数据库               |
| `bin/rails routes`      | 列出所有路由                               |
| `bin/rails test`        | 运行测试套件（Minitest）                   |
| `bundle exec rspec`     | 运行测试套件（RSpec，如果使用）            |
| `bin/rails assets:precompile` | 编译生产资产                           |
| `bin/rubocop`           | 运行 Ruby 检查器                           |
| `yarn lint`             | 运行 JavaScript/TypeScript 检查器          |

8. 测试

## 测试

### 运行测试

```bash
# 运行所有测试（Minitest）
bin/rails test

# 运行所有测试（RSpec，如果使用）
bundle exec rspec

# 运行特定测试文件
bin/rails test test/models/user_test.rb
bundle exec rspec spec/models/user_spec.rb

# 运行匹配模式的测试
bin/rails test -n /creates_user/
bundle exec rspec -e "creates user"

# 运行系统测试（浏览器测试）
bin/rails test:system

# 运行覆盖率测试（SimpleCov）
COVERAGE=true bin/rails test

测试结构

test/ # Minitest 结构
├── controllers/ # 控制器测试
├── models/ # 模型单元测试
├── integration/ # 集成测试
├── system/ # 系统/浏览器测试
├── fixtures/ # 测试数据
└── test_helper.rb # 测试配置

spec/ # RSpec 结构（如果使用）
├── models/
├── requests/
├── system/
├── factories/ # FactoryBot 工厂
├── support/
└── rails_helper.rb

编写测试

Minitest 示例：

require "test_helper"

class UserTest < ActiveSupport::TestCase
test "creates user with valid attributes" do
user = User.new(email: "test@example.com", name: "Test User")
assert user.valid?
end

test "requires email" do
user = User.new(name: "Test User")
assert_not user.valid?
assert_includes user.errors[:email], "can't be blank"
end
end

RSpec 示例：

require "rails_helper"

RSpec.describe User, type: :model do
describe "validations" do
it "is valid with valid attributes" do
user = build(:user)
expect(user).to be_valid
end

    it "requires an email" do
      user = build(:user, email: nil)
      expect(user).not_to be_valid
      expect(user.errors[:email]).to include("can't be blank")
    end

end
end

前端测试

对于 Inertia/React 组件：

yarn test

import { render, screen } from '@testing-library/react'
import { Dashboard } from './Dashboard'

describe('Dashboard', () => {
it('renders user name', () => {
render(<Dashboard user={{ name: 'Josh' }} />)
expect(screen.getByText('Josh')).toBeInTheDocument()
})
})


### 9. 部署

根据检测到的平台定制（查找 Dockerfile, fly.toml, render.yaml, kamal/, 等）：

```markdown
## 部署

### Kamal（推荐用于 Rails）

如果使用 Kamal 部署：

```bash
# 设置 Kamal（第一次）
kamal setup

# 部署
kamal deploy

# 回滚到前一个版本
kamal rollback

# 查看日志
kamal app logs

# 在生产环境运行控制台
kamal app exec --interactive 'bin/rails console'

配置在 config/deploy.yml 中。

Docker

构建和运行：

# 构建镜像
docker build -t myapp .

# 运行带环境变量
docker run -p 3000:3000 \
 -e DATABASE_URL=postgresql://... \
 -e SECRET_KEY_BASE=... \
 -e RAILS_ENV=production \
 myapp

Heroku

# 创建应用
heroku create myapp

# 添加 PostgreSQL
heroku addons:create heroku-postgresql:mini

# 设置环境变量
heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)

# 部署
git push heroku main

# 运行迁移
heroku run bin/rails db:migrate

Fly.io

# 启动（第一次）
fly launch

# 部署
fly deploy

# 运行迁移
fly ssh console -C "bin/rails db:migrate"

# 打开控制台
fly ssh console -C "bin/rails console"

Render

如果 render.yaml 存在，连接您的仓库到 Render，它将自动部署。

手动设置：

创建新的 Web 服务
连接 GitHub 仓库
设置构建命令：bundle install && bin/rails assets:precompile
设置启动命令：bin/rails server
在仪表板中添加环境变量

手动/VPS 部署

# 在服务器上：

# 拉取最新代码
git pull origin main

# 安装依赖
bundle install --deployment

# 编译资产
RAILS_ENV=production bin/rails assets:precompile

# 运行迁移
RAILS_ENV=production bin/rails db:migrate

# 重启应用服务器（例如，通过 systemd 的 Puma）
sudo systemctl restart myapp


### 10. 故障排除

```markdown
## 故障排除

### 数据库连接问题

**错误：** `could not connect to server: Connection refused`

**解决方案：**

1. 验证 PostgreSQL 正在运行：`pg_isready` 或 `docker ps`
2. 检查 `DATABASE_URL` 格式：`postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
3. 确保数据库存在：`bin/rails db:create`

### 待处理迁移

**错误：** `Migrations are pending`

**解决方案：**
```bash
bin/rails db:migrate

资产编译问题

错误： The asset "application.css" is not present in the asset pipeline

解决方案：

# 清除并重新编译资产
bin/rails assets:clobber
bin/rails assets:precompile

Bundle 安装失败

错误： 原生扩展构建失败

解决方案：

确保系统依赖已安装：

# macOS
brew install postgresql libpq

# Ubuntu
sudo apt-get install libpq-dev

重试：bundle install

凭据问题

错误： ActiveSupport::MessageEncryptor::InvalidMessage

解决方案： 主密钥与凭据文件不匹配。要么：

从其他团队成员获取正确的 config/master.key
或重新生成凭据：rm config/credentials.yml.enc && bin/rails credentials:edit

Vite/Inertia 问题

错误： Vite Ruby - Build failed

解决方案：

# 清除 Vite 缓存
rm -rf node_modules/.vite

# 重新安装 JS 依赖
rm -rf node_modules && yarn install

Solid Queue 问题

错误： 作业未处理

解决方案： 确保队列工作者正在运行：

bin/jobs

# 或
bin/rails solid_queue:start


### 11. 贡献（可选）

如果是开源或团队项目，包括此部分。

### 12. 许可证（可选）

---

## 写作原则

1. **极其详尽** - 如有疑问，包括它。更多细节总是更好。

2. **自由使用代码块** - 每个命令都应该是可复制粘贴的。

3. **展示示例输出** - 当有帮助时，展示用户应该期望看到的内容。

4. **解释为什么** - 不只是说“运行这个命令”，解释它做什么。

5. **假设全新机器** - 写作时假设读者从未见过此代码库。

6. **使用表格参考** - 环境变量、脚本和选项作为表格很好用。

7. **保持命令最新** - 如果项目使用 pnpm，则使用 `pnpm`；如果使用 npm，则使用 `npm`，等等。

8. **包括目录** - 对于超过约200行的README，在顶部添加目录。

---

## 输出格式

生成一个完整的 README.md 文件，包含：

- 适当的 Markdown 格式
- 带语言提示的代码块（`bash, `typescript`, 等）
- 表格在适当时
- 清晰的部分层次
- 长文档的链接目录

将 README 直接写入项目根目录下的 `README.md`。