Claude Code / Codex
指令提示词与模板合集

读取你（本代理）会加载的指令文件（CLAUDE.md / AGENTS.md 等），
指出 AI 代理容易忽略的薄弱之处，然后将其改写为有效的形式。

需要关注的方面：
- 把含糊的措辞改成祈使句（务必做 X / 绝不做 Y）
- 加入"完成的定义"和验证步骤（运行 lint / test）
- 把禁止事项具体到对象（目录名、命令名）
- 如果太长，就精简到只剩你想要强制执行的核心

先用要点列出薄弱之处，然后输出改写后的完整版本，
并将其应用到该指令文件中。

在确定本仓库实际的 build / test / lint 命令之后，
向你会加载的指令文件（CLAUDE.md / AGENTS.md 等）中
添加一个"完成的定义"小节。

要求：
- 写成"在满足以下全部条件之前不要报告完成"形式的清单
- 明确写出真实的 lint 和 test 命令
- 包含：不在改动的文件中遗留 TODO 或调试日志，以及重读你自己的 diff

不要破坏已有内容；只添加该小节。

自动识别本仓库的语言和框架，并将相应的最佳实践规则
添加到你会加载的指令文件（CLAUDE.md / AGENTS.md 等）中。

示例：
- Next.js：Server/Client 边界（默认为 Server，尽量少用 use client）
- Laravel：通过 Form Request 进行校验、迁移规约
- Python：类型注解，绝不覆盖或捏造原始数据

在追加之前，先用一行注明你的判断依据（你根据哪些文件判断的）。
不要与已经写过的内容重复。

向你会加载的指令文件（CLAUDE.md / AGENTS.md 等）中，
按本仓库的具体情况添加以下"绝对规则"。

- 绝不提交密钥、.env 或凭据
- 未经指示绝不 push / force-push
- 在边界处校验输入 / 绝不擅自放松认证或授权
- 绝不对生产数据库执行破坏性命令（DROP / TRUNCATE / migrate:fresh 等）
- 每当你改变行为，务必添加或更新测试

如果已存在类似规则，不要重复；只补全缺失的部分。

把这份 `CLAUDE.md` 的内容转换为面向 OpenAI Codex 的 `AGENTS.md` 格式
并写出来。

- 保持原意，但重新组织为便于 Codex 阅读的结构（标题、要点列表）
- 命令、绝对规则和完成的定义保持原样
- 在根目录输出为 `AGENTS.md`

把这份 `CLAUDE.md` 的内容转换为 Cursor 的 Project Rules 格式
（`.cursor/rules/` 下的 `.mdc` 文件）。

- 把规则拆分为有意义的单元
- 把应当始终生效的规则，与只对特定文件类型生效的规则分开
- 在每个文件顶部设置恰当的生效条件（globs 等）

检查这个 monorepo 的结构，并创建你（本代理）会加载的指令文件
（Claude Code 使用 CLAUDE.md，Codex 使用 AGENTS.md 等），
按如下方式拆分。

- 在根目录：适用于整个仓库的通用规则
  （提交规约、密钥保护、整体的完成的定义）
- 在每个包/应用的目录中：只放该技术栈专属的规则和命令

避免重复，并在每个包中加一行注明"遵循根目录的通用规则"。
最后，列出你在哪个目录放了什么，作为报告。

# 项目：<name>

## 这是什么
用一段话概述该应用：它做什么、谁来使用，以及技术栈
（语言、框架、数据库、运行时）。

## 命令
- 开发服务器: `npm run dev`
- 构建:       `npm run build`
- 测试:       `npm test`
- Lint:       `npm run lint`

## 规约
- 语言为 TypeScript（strict）。不要使用 `any`。
- 与你当前正在编辑的文件风格保持一致。完成前务必通过 Lint。
- 改动保持最小；不要碰无关行（不做无关的重新格式化）。

## 绝对规则（严格执行）
- 在报告完成之前，务必运行上面的测试和 Lint 并使其通过。
- 绝对、绝对不要提交密钥、.env 或构建产物。
- 优先编辑现有文件，而不是新建文件。
- 当需求含糊时，在做出较大改动前只问一个澄清性问题。

## 禁止触碰的范围（除非另有指示）
- CI 配置、依赖版本、基础设施配置。

# <name>

- 技术栈: <例如 Next.js + TypeScript + PostgreSQL>
- 完成前务必运行: `npm run lint` 和 `npm test`（两者都必须通过）
- 与现有风格保持一致。不要重新格式化无关行。
- 不要提交密钥或 .env。未经指示不要 push。
- 含糊时不要猜测；只问一个问题。

# Next.js（App Router）+ TypeScript

## 技术栈
Next.js（App Router）、TypeScript strict、Tailwind CSS、<your-ORM>

## 命令
- 开发:   `npm run dev`
- 构建:   `npm run build`   # 必须无类型错误地通过
- Lint:  `npm run lint`
- 测试:   `npm test`

## 架构规则
- 默认使用 Server Component。仅当需要 state、effect 或浏览器 API 时，
  才加上 "use client"。让 Client Component 保持小巧并位于末端。
- 在 Server Component 或 Route Handler 中获取数据。
  不要在 useEffect 中获取初始数据。
- 把组件与其路由段就近放置。共享 UI 放在 `components/`。
- 务必在边界处对外部输入做模式校验（例如 Zod）。

## 规约
- 禁用 `any`。为公开函数标注明确的返回类型。
- 使用现有的设计令牌 / Tailwind 类。不要擅自增加颜色。
- 让 `page.tsx` 保持轻薄；把逻辑下沉到函数和组件中。

## 完成的定义
`npm run build`、`npm run lint` 和 `npm test` 全部以退出码 0 通过。
无 `any`、无未使用的 export、无遗留的 console.log。

# React（Vite）+ TypeScript

## 命令
- 开发:   `npm run dev`
- 构建:   `npm run build`
- Lint:  `npm run lint`
- 测试:   `npm test`（Vitest + Testing Library）

## 规则
- 只用函数组件加 Hooks。不要使用类组件。
- 按"局部 -> Context -> 状态库"的顺序，把状态保持在最低限度。
  不要无谓地把状态上提到全局。
- 把副作用限制在 useEffect 中，并正确编写依赖数组。
- 分离 UI 与逻辑。把数据获取归拢到专用 Hook（useXxx）中。
- 可访问性：为交互元素赋予恰当的角色和键盘操作。

## 规约
- 禁用 `any`。用类型定义 props。
- 与现有组件和样式的风格保持一致。

## 完成的定义
`npm run build`、`npm run lint` 和 `npm test` 以退出码 0 通过。

# Node.js API（Express / Hono）+ TypeScript

## 命令
- 开发:   `npm run dev`
- 构建:   `npm run build`
- 测试:   `npm test`
- Lint:  `npm run lint`

## 规则
- 在边界处对所有输入（body、query、params、headers）做模式校验。
- 不要吞掉错误。通过集中的错误处理器以带类型的方式返回它们。
- 从环境变量读取密钥。不要在代码中硬编码。
- 对数据库访问分层（route -> service -> repository）。
- 返回一致的 JSON 形状（统一成功与失败的形状）。

## 绝对规则
- 不要擅自跳过或放松认证 / 授权逻辑。
- 新增对外暴露的端点时，务必核实授权。
- 不要把个人信息、令牌或密码写入日志。

## 完成的定义
`npm test`（正常路径 + 错误情形）和 `npm run lint` 通过。

# Laravel + PHP

## 命令
- 启动:   `php artisan serve`
- 迁移:   `php artisan migrate`
- 测试:   `php artisan test`
- 格式化: `./vendor/bin/pint`   # 完成前运行

## 规约（遵循 Laravel 的方式）
- 使用 Eloquent 关联。没有明确理由就避免裸 SQL。
- 在 Form Request 类中校验输入。不要在控制器内做。
- 让控制器保持轻薄。把业务逻辑下沉到 Service / Action。
- 每次结构变更都新建一个迁移。不要编辑已经运行过的迁移。
- 使用命名路由和路由模型绑定。

## 绝对规则
- 绝对、绝对不要提交 `.env` 或真实凭据。
- 不要对生产数据库运行 `migrate:fresh` 之类的破坏性命令。
- 每当你改变行为，务必添加或更新测试（`php artisan test`）。

## 完成的定义
`php artisan test` 和 `./vendor/bin/pint --test` 两者都通过。

# Python / 数据分析

## 环境
- 使用项目的 venv `.venv`。不要全局安装。
- 安装: `pip install -r requirements.txt`
- 运行: `python -m src.main`
- 测试: `pytest`
- 格式化: `ruff check .` 和 `ruff format .`

## 规约
- 为每个函数签名添加类型注解。如已配置，运行 `mypy src`。
- 不要把逻辑写进 notebook。可复用代码放在 `src/`。
- 对任何用到随机性的处理固定 seed，使结果可复现。

## 数据绝对规则（最重要）
- 不要悄悄填补或捏造缺失值。若存在缺失值，
  报告它们并确认如何处理。
- 不要覆盖原始数据文件。把输出写到 `data/processed/`。
- 在代码注释中记录所有假设（过滤条件、排除的行、单位）。

## 完成的定义
`pytest` 通过，`ruff check .` 干净，并且结果能从干净状态复现。

# Go

## 命令
- 构建:   `go build ./...`
- 测试:   `go test ./...`
- 格式化: `gofmt -w .` 和 `go vet ./...`

## 规约
- 不要吞掉错误。务必用 `if err != nil` 处理，并带上下文返回
  （`fmt.Errorf("...: %w", err)`）。
- 用提前 return 保持浅层嵌套。
- 仅在需要时使用并发。注意 goroutine 泄漏和竞态
  （让 `go test -race` 通过）。
- 为导出符号写注释。优先使用标准库。

## 绝对规则
- 不要添加不必要的抽象或接口（需要时再创建）。
- 添加依赖前，先检查标准库是否足够。

## 完成的定义
`go build ./...`、`go vet ./...` 和 `go test -race ./...` 全部通过。

# Rust

## 命令
- 构建:   `cargo build`
- 测试:   `cargo test`
- Lint:  `cargo clippy -- -D warnings`
- 格式化: `cargo fmt`

## 规约
- 不要在生产代码中随意使用 `unwrap()` / `expect()`。
  用 `?` 或 match 正确处理 `Result` / `Option`。
- 原则上禁用 `unsafe`。若确有必要，在注释中说明理由。
- 在借用和生命周期上听从编译器。在用 `clone()` 逃避之前先重新审视设计。
- 用 `thiserror` / `anyhow` 等让错误类型有意义。

## 完成的定义
`cargo build` 和 `cargo test` 通过，并且
`cargo clippy -- -D warnings` 报告零警告。

# Ruby on Rails

## 命令
- 启动:   `bin/rails server`
- 迁移:   `bin/rails db:migrate`
- 测试:   `bin/rails test`（或 `bundle exec rspec`）
- 格式化: `bundle exec rubocop -A`

## 规约（遵循 Rails 的方式）
- 尊重"约定优于配置"；不要自创结构。
- 避免臃肿的控制器 / 模型。把逻辑下沉到 Service / Concern。
- 用 strong parameters 限制输入。
- 避免 N+1（使用 `includes`）。
- 结构变更新建一个迁移。不要编辑已经运行过的迁移。

## 绝对规则
- 绝对、绝对不要提交 `.env` 或凭据。
- 不要对生产数据库运行破坏性命令。
- 当你改变行为时，添加或更新测试。

## 完成的定义
测试和 `bundle exec rubocop` 通过。

# SQL / 数据库迁移

## 绝对规则（数据保护优先）
- 不要擅自对生产数据执行破坏性操作
  （DROP / TRUNCATE / 无条件的 DELETE 或 UPDATE）。
- 迁移必须提供回滚步骤，而不只是前进方向。
- 不要编辑已经运行过的迁移。总是新建迁移。
- 分阶段删除或重命名列（"添加 -> 迁移 -> 废弃"）；不要一步到位。

## 查询规约
- 避免 `SELECT *`；指明你需要的列。
- 确认 WHERE / JOIN 条件能用上索引。
- 把大批量更新拆成批次，让锁定时间保持短暂。
- 对于破坏性的验证查询，先用 `SELECT` 确认受影响的行数再执行。

## 完成的定义
在等同于预发布的环境中应用和回滚都成功，并且你已确认
对现有数据没有意外改动。

# 测试驱动的做法

改变行为时，每次都遵循这个循环：
1. 先写一个表达期望行为的"会失败的测试"。
2. 运行测试，确认它因正确的原因而失败。
3. 写出让测试通过所需的最少代码。
4. 运行整个测试套件，确认全部变绿。
5. 在保持绿色的同时进行重构。

## 绝对规则
- 不要为了让套件通过而删除或跳过测试。
- 不要为了让它变绿而弱化断言。
- 如果一个测试确实有错，在修改它之前说明原因。
- 没有测试的新代码不算"完成"。

## 完成的定义
整个套件通过，覆盖率没有下降，并且把实现回退后
新测试会失败（即它是有意义的测试）。

# 调试的做法

按这个顺序推进。不要靠猜来修：
1. 确定复现步骤（如何触发这个 bug）。
2. 各用一句话写出期望行为和实际行为。
3. 提出一个假设。在修复前，用日志或最小复现来验证它。
4. 一旦定位到原因，施加最小修复。
5. 修复后，通过复现步骤确认 bug 已消失，且现有测试通过。
6. 如有可能，添加一个能捕捉这个 bug 的回归测试。

## 绝对规则
- 在原因未明时，不要同时改动多处。
- 不要止步于"暂时能用"。说明它为何被修好了。
- 不要把无关的重构混进调试中。

# 重构的做法

## 核心原则
不要改变对外可观察的行为。对任何输入都不改变其输出或副作用。

## 步骤
1. 先确认目标区域有测试且为绿色。
   若没有，先写特征测试把当前行为固定下来。
2. 以小而单一的步骤改动，每步之后都运行测试。
3. 保持一次提交 = 一种改进。

## 绝对规则
- 不要把新增功能或修复 bug 混进重构（让它们成为独立的工作）。
- 一旦测试变红，立刻在原地停下。不要继续推进。
- 不要擅自改变公开 API 的签名（需要时先确认）。

## 完成的定义
所有测试保持绿色，代码可读性更高、重复更少。

# 如何编写设计文档

在实现之前，先用文字写出以下内容（不要写代码）：

## 1. 目标
要解决的问题，以及可以称之为达成的条件（成功标准）。

## 2. 现状与约束
现有的配置、依赖，以及需要遵守的约束（性能、兼容性、截止日期）。

## 3. 设计方案
- 选定的方案，以及你考虑过并否决的方案（以及原因）。
- 数据流向、关键接口，以及要改动的文件。

## 4. 风险与未决问题
可能出问题的地方、需要确认的假设，以及需要做决策的要点。

## 5. 计划
把实现拆成小步骤，排列成可验证的单元。

## 规则
- 在这份设计被批准之前，不要开始实现。
- 把未知项列在"未决问题"下；不要用你自己的假设来填补它们。

# 如何进行大规模变更

## 核心原则
避免一次性的巨大变更。拆分它，使每一步都可独立审查、
测试，并（理想情况下）可部署。

## 步骤
1. 把通往最终形态的变更，分解为一系列小而独立的步骤，并呈现出来。
2. 对每一步，用 1-2 行写出"做什么 / 为什么 / 影响范围"。
3. 每一步之后运行整个测试套件，确认绿色后再继续。
4. 在保持向后兼容的同时推进（添加 -> 迁移 -> 废弃旧路径）。

## 绝对规则
- 不要一次性改写大片区域然后"稍后一起测试"。
- 如果某一步变得太大，进一步拆分它。
- 让每一步都保持在可回退的粒度。

## 完成的定义
所有步骤完成后测试为绿色，且每个中间提交也都没有损坏。

# 代码审查指令

审查变更，按严重程度分组，并按这个顺序报告：
1. CRITICAL - 安全漏洞、数据丢失、崩溃、认证被攻破
2. HIGH     - 逻辑 bug、竞态条件、缺失的错误处理
3. MEDIUM   - 性能问题、缺失测试、令人困惑的命名
4. LOW      - 细微的风格挑剔（仅当没有更高级别问题时）

## 如何报告
- 每条发现：文件:行 / 哪里出错 / 为何重要 / 一个具体的修复方案。
- 只引用最小的相关片段。不要粘贴整个文件。
- 如果某个改动是正确的，就明确说出来。不要捏造问题。

## 不应做的事
- 不要把真正的 bug 埋在一堆 LOW 级挑剔之下。
- 不要改写整个文件。提出最小的 diff。
- 除非有实际危害，否则不要标记 diff 范围之外的行。

## 输出
最后给出一行结论：APPROVE / REQUEST CHANGES / BLOCK，并附上理由。

# Git / PR 规则

## 提交
- 使用 Conventional Commits：`type(scope): summary`
  type: feat、fix、refactor、test、docs、chore。
- 一次提交 = 一个逻辑变更。保持小巧且可审查。
- 在正文中，写"为什么"而不是"做了什么"。

## 绝对规则
- 未经指示不要 `git push`。
- 不要在共享分支 / main 上 force-push、rebase 或 amend。
- 不要提交密钥、.env、凭据或大型二进制文件。
- 按名称添加文件。不要用 `git add -A` 把一切都卷进来。

## 拉取请求
- 标题控制在 70 个字符以内。正文为"概要" + "测试计划（清单）"。
- 注明任何破坏性变更。
- 不要合并。创建 PR 并报告 URL。

# 安全审查指令

按以下视角依次检查变更，并报告发现的任何问题，
附上严重程度评级：
- 缺失的输入校验（注入：SQL / 命令 / XSS / SSRF）
- 认证/授权缺口（缺失的权限检查、权限提升）
- 密钥泄露（硬编码的密钥/令牌、输出到日志）
- 不安全的默认值（过度暴露、宽松的 CORS、未校验的重定向）
- 依赖中的已知漏洞、不安全的加密 / 随机数使用

## 如何报告
- 每条发现：位置 / 攻击场景（它可能如何被利用）/ 一个具体的修复方案。
- 把你不确定的疑点标记为"需确认"（不要悄悄跳过它们）。
- 如果没有问题，就连同你检查过的视角一起声明"无问题"。

## 不应做的事
- 不要生成实际的攻击代码或利用步骤（只给出修复方案）。

# Docker / 基础设施工作规则

## 绝对规则（防止破坏优先）
- 不要擅自对生产或共享环境运行破坏性命令
  （`docker system prune`、删除卷、`down -v` 等）。
- 把镜像固定到确定的标签。不要依赖 `latest`。
- 通过环境变量 / 密钥管理来传递密钥。
  不要把它们烧进 Dockerfile 或镜像里。
- 把暴露的端口和权限（privileged 等）保持在必要的最小限度。

## 规约
- 用多阶段构建让 Dockerfile 保持小巧，并留意层缓存。
- 以非 root 用户运行。
- 改动后，在本地构建并启动以验证，然后再报告。

## 完成的定义
`docker build` 通过，容器启动，且健康检查 / 基本操作可被确认。

# 依赖规则

## 绝对规则
- 添加依赖前，检查标准库或现有依赖是否足够。
- 添加新依赖时，用一行注明其用途、替代方案和维护状况。
- 不要擅自升级大版本（仅当被指示时）。
- 不要擅自重新生成锁文件（package-lock.json 等）。
- 避免来源可疑、或星标极少、维护极差的包。

## 步骤
1. 说明添加或更新的理由。
2. 添加后，确认构建和测试通过。
3. 确认许可证与你的使用场景不冲突。

## 完成的定义
依赖变更后构建和测试通过，并且你能解释锁文件中的差异。