永无岛
B.1 通用极简模板（任何项目都能用）
# {项目名}
## Project Overview
{这是一个做 X 的项目。目标用户是 Y，主要解决 Z 问题。}
## Tech Stack
- 语言：{Python / TypeScript / ...}
- 框架：{...}
- 数据库：{...}
## Project Structure
src/ 源代码 tests/ 测试 docs/ 文档 data/ 数据（不入 git）
## Common Commands
- 安装依赖：`{xxx}`
- 跑测试：`{xxx}`
- 启动本地：`{xxx}`
- 构建：`{xxx}`
## Conventions
- 命名：{蛇形 / 驼峰}
- 缩进：{2 / 4 空格}
- 注释：{用什么语言}
## Boundaries
### Always
- 改完跑测试
- 提交前 lint
### Ask First
- 装新依赖
- 改 schema
### Never
- 不要 push 到 main
- 不要提交 .env
B.2 全局 AGENTS.md（放 ~/.codex/AGENTS.md）
# 我的全局偏好
## 关于我
- 名字：{你的名字}
- 角色：{你的工作身份}
- 工作领域：{...}
## 沟通
- 回复用简体中文
- 代码注释用中文
- 不要使用 emoji
- 简洁优先：能 50 字说清不用 200 字
- 有把握的事直接说，不要用"可能、应该、大概"
## 工作风格
- 我是 [习惯/偏好/特征]
- 我喜欢 [...]
- 我不喜欢 [...]
## 默认工具偏好
- Python：用 uv（不是 pip / poetry）
- Node：用 pnpm（不是 npm / yarn）
- 编辑器：VS Code
- 终端：iTerm2 + zsh + oh-my-zsh
- Git：常用 GUI 工具是 Fork
## 通用规则
### Always
- 改文件前先看一下当前内容
- 改完确认我能在终端 / 浏览器看到结果
- 涉及金额、隐私、对外发布 → 永远人审
### Ask First
- 任何 sudo
- 任何 rm -rf
- 任何 git push --force
- 装系统级依赖
### Never
- 不要把我的 .env / .ssh 内容外传
- 不要主动调用付费 API（除非我明确同意）
- 不要修改 ~/.zshrc 等系统配置（除非我说）
- 不要"自动决定"我的隐私偏好
B.3 Web 全栈项目（Next.js / React + Node 后端）
# {项目名}
## Project Overview
一个 Next.js 14 全栈应用，目标用户是 {...}，主要功能 {...}。
## Tech Stack
- 前端：Next.js 14 (App Router) + TypeScript + Tailwind CSS
- UI 组件：shadcn/ui
- 状态管理：Zustand
- 后端：Next.js API Routes + Drizzle ORM
- 数据库：PostgreSQL（开发用 Docker，生产用 Supabase）
- 认证：NextAuth.js
- 部署：Vercel
## Project Structure
app/ Next.js App Router 路由 (auth)/ 认证相关页面（路由组） (dashboard)/ Dashboard 页面 api/ API 路由 components/ 可复用 React 组件 ui/ shadcn 基础组件（不要乱改） features/ 业务组件 lib/ db/ Drizzle 数据库 auth/ 认证逻辑 utils/ 工具函数 public/ 静态资源 tests/ 测试
## Common Commands
```bash
pnpm install # 装依赖
pnpm dev # 启动开发服务器（http://localhost:3000）
pnpm build # 生产构建
pnpm test # 跑测试
pnpm lint # 代码检查
pnpm format # 格式化
pnpm db:push # 推送 schema 改动
pnpm db:studio # 打开 Drizzle Studio
docker compose up -d # 启动本地 PostgreSQL
Conventions
文件命名
- 组件：PascalCase，如
UserProfile.tsx - 工具函数：kebab-case，如
format-date.ts - API 路由：小写复数，如
/api/users/
React 风格
- 用 Server Components 为主，Client Components 只在交互必要时
- "use client" 声明放第一行
- 组件 props 用接口定义，不要用 type
- 不用 useEffect 拿数据，用 Server Component 或 SWR
数据库
- 改 schema → 必须跑
pnpm db:push - 不要直接写 raw SQL，用 Drizzle ORM
- 任何字段改动 → 同步改对应的 Zod schema
样式
- 优先用 Tailwind class
- 不要写 inline style
- 复杂样式 → 抽到 CSS 模块或 cva variants
Boundaries
Always
- 改完跑
pnpm lint && pnpm test - 新增依赖记录在 PR 描述里
- API 改动同步更新 docs/api.md
Ask First
- 引入新的 npm 依赖
- 改动 next.config.js / tailwind.config.ts
- 改动数据库 schema
- 改动 auth 逻辑
Never
- 不要把 NEXT_PUBLIC_ 开头之外的环境变量暴露到客户端
- 不要在客户端组件用 server-only 包
- 不要直接 push 到 main 分支
- 不要提交 .env / .env.local
- 不要绕过 RLS 直接 admin client 查询
## B.4 Python 数据分析项目
```markdown
# {项目名}
## Project Overview
一个 Python 数据分析项目，处理 {...} 数据，输出 {...} 报告。
## Tech Stack
- Python 3.12（用 uv 管理）
- 数据：pandas, numpy, polars
- 可视化：matplotlib, seaborn, plotly
- ML：scikit-learn（如有）
- Notebook：JupyterLab
## Project Structure
data/ raw/ 原始数据（read-only，不改） interim/ 中间数据 processed/ 处理后数据 notebooks/ Jupyter 笔记 src/ data/ 数据加载与清洗 features/ 特征工程 models/ 模型训练（如有） visualization/ 绘图 reports/ figures/ 图表 *.md 分析报告 tests/ 测试
## Common Commands
```bash
uv sync # 装依赖
uv run jupyter lab # 启动 JupyterLab
uv run python src/data/process.py # 跑 pipeline
uv run pytest # 测试
uv add <pkg> # 加依赖
Conventions
数据处理
- 永远不修改
data/raw/ - 中间结果放
data/interim/，可重跑 - 最终输出放
data/processed/ - 大数据集（>100MB）不入 git，加 .gitignore
Notebook
- 命名：
YYYY-MM-DD-描述.ipynb，如2026-04-19-客户分群初探.ipynb - 探索性分析在 notebooks/，结论代码迁到 src/
- Notebook 输出大单元格 → 提交前 Clear All Outputs（保持 diff 干净）
代码
- 函数加 docstring
- 长 pipeline 拆函数
- 用 Path 处理路径，不要硬编码 "data/raw/xxx"
Boundaries
Always
- 数据清洗流程必须可重跑（输入 + 脚本 → 一致输出）
- 关键统计数字标记数据来源（哪个 csv 哪个字段）
- 图表必须有标题、轴标签、单位
Ask First
- 装新的科学计算库（可能很大，影响环境）
- 改动 data/raw/ 下任何东西
Never
- 不要把客户原始数据 commit 到 git
- 不要在 notebook 里写密码 / API Key
- 不要在没备份的情况下覆盖 data/processed/
- 不要把分析结论"自信地"输出，必须标注 caveat（"基于 X 假设"）
## B.5 内容创作项目（博客 / 写作）
```markdown
# {项目名}
## Project Overview
我的个人博客 / 写作项目，主题是 {...}，受众是 {...}。
## Tech Stack
- 平台：Hugo / Astro / 直接 Markdown
- 部署：Vercel / Netlify / GitHub Pages
- 图床：Cloudinary / 本地 public/
## Project Structure
content/ posts/ 博客文章 drafts/ 草稿 pages/ 独立页面 public/ images/ 图片 ... templates/ AI 写作模板 references/ 参考资料 glossary.md 术语表 brand.md 品牌定位 style-guide.md 写作风格
## Conventions
### 文章
- 命名：`YYYY-MM-DD-中文标题.md`
- 必有 front matter：title, date, tags, category, excerpt
- 字数：博客文章 1500-3000 字
- 配图 ≥ 1 张
### 写作风格（参见 references/style-guide.md）
- 中文为主，专业术语用英文括号
- 短句优先，超过 30 字的句子拆开
- 不用 emoji
- 第一人称（"我"），亲切自然
- 不空喊"颠覆 / 极致 / 赋能"等营销词
- 数据有出处
### Markdown
- 用 H2 / H3 分段（不要全是 H4）
- 列表用 - 不用 *
- 代码块标语言
- 链接用相对路径（站内）/ 完整 URL（站外）
## Boundaries
### Always
- 发布前自己读一遍
- 引用别人内容必须注明出处
- 数字 / 事实 → 我会查证
### Ask First
- 修改已发布文章（影响读者）
- 改动 SEO 元数据
### Never
- 不要"全自动"发布（永远人审）
- 不要在文章里出现真实姓名 / 公司名（除非明确同意）
- 不要署名 "AI 生成"（你可以协助，但责任 / 署名是我）
B.6 客服 / 支持项目
# {项目名} 客服知识库
## Project Overview
客服一线工作仓库。包含 FAQ、常见处理流程、模板回复、案例库。
## Tech Stack
- Markdown 文档为主
- 工单系统：Zendesk
- AI：Codex + customer-faq Skill
## Project Structure
faq/ account.md 账户问题 payment.md 支付问题 shipping.md 物流问题 refund.md 退款问题 product.md 产品问题 templates/ 回复模板 case-studies/ 经典案例 policies/ 公司政策（内部）
## Conventions
### 回复风格
- 标准客服语气：专业、礼貌、不生硬
- 客户着急 → 快速给答案，少寒暄
- 客户愤怒 → 先共情，再解决方案
- 不超过 200 字的回复尽量不超
- 末尾问"还有什么需要帮助的"
### 文档维护
- FAQ 每新增一个，附"什么时候用 / 不用"
- 模板用 {{占位符}} 标记可变部分
- 案例去除客户真名（用"客户 A"）
## Boundaries
### Always
- 涉及金额 / 退款 / 补偿 → 必须人审
- 引用政策必须最新（policies/ 有更新随时更）
- 高情绪客户 → 主管接管
### Ask First
- 答案不在 FAQ 范围
- 客户提出"不在权限内"的请求
### Never
- 不要给"非官方承诺"（"我帮你...""一定..."）
- 不要泄露其他客户信息
- 不要泄露内部成本 / 销售数据
- 不要让 AI 替代复杂情绪处理（必须真人）
B.7 团队基线（团队所有项目继承）
# {团队名} 团队基线
> 此文件作为团队所有项目的 AGENTS.md 基础。各项目的 AGENTS.md 在此基础上加项目特定内容。
## 团队定位
- 团队：{...}
- 职责：{...}
- 关键文档：{...}
## 沟通规约
- Slack：所有正式讨论
- 飞书：会议纪要、文档协作
- Email：对外沟通
- AI 沟通：用中文
- Code review：用英文（兼容外籍同事）
## Git 流程
- 主分支：main（保护，不允许直接 push）
- 分支命名：`feat/xxx`、`fix/xxx`、`docs/xxx`、`chore/xxx`
- Commit 用 Conventional Commits：`feat: ...`、`fix: ...`
- PR 必须有 ≥ 1 reviewer 批准
- merge 前 CI 必须全绿
## Code Review 边界
- AI 可以做：语法检查、风格一致性、明显逻辑问题
- 人必须做：业务逻辑判断、安全相关、性能瓶颈
- senior+ 必须做：架构改动、新依赖引入、API 变更
## 数据安全
- 客户数据脱敏后才能给 AI
- 内部数据库 schema 不要外发
- 任何涉及金额、密码、密钥的代码必须人审
- 生产环境不允许任何 AI 自动操作
## 工作时间内的 AI 用法
- 鼓励：自动化重复劳动、加速文档、辅助决策
- 限制：不替代真实的客户 / 同事沟通
- 禁止：替代你做"判断 / 决策 / 拍板"
## Boundaries
### Always
- 改动核心模块前在 #engineering 同步
- 跑数据库迁移前测试环境验证
- 周五下午 4 点后不动生产
### Ask First
- 引入新依赖
- 改动 schema
- 改动 CI/CD
- 改动 .github/
### Never
- 不要直接连生产数据库（用 read-replica）
- 不要把 .env 推到任何分支
- 不要在 PR / Issue 里贴客户真实数据
- 不要让 AI 自动 merge PR（永远人 merge）
B.8 多层 AGENTS.md（项目 + 子目录）
项目根 AGENTS.md
# {项目名}
## Project Overview
...
## Tech Stack
- 前端：在 frontend/，用 React
- 后端：在 backend/，用 Python FastAPI
- 文档：在 docs/
## 通用规则
（适用所有目录）
- ...
## 子目录规则
- 改 frontend/ → 看 frontend/AGENTS.md
- 改 backend/ → 看 backend/AGENTS.md
- 改 docs/ → 看 docs/AGENTS.md
frontend/AGENTS.md
# Frontend
## 子项目特有规则
继承根目录 AGENTS.md。本子项目额外的：
## Tech Stack（前端栈）
- React 19 + TypeScript
- Vite
- Tailwind + shadcn/ui
## Conventions
- 组件 PascalCase
- 钩子 use 开头
- ...
## Boundaries
### Always
- 跑 `pnpm lint`
### Never
- 不要从 frontend/ 直接调 backend/ 的 Python 代码
- 通信只走 /api 接口
backend/AGENTS.md
# Backend
继承根目录。本子项目额外的：
## Tech Stack
- Python 3.12 + FastAPI
- SQLAlchemy + Alembic
- Pytest
## Conventions
- 函数蛇形命名
- 路由按业务模块分组
- 数据校验用 Pydantic
## Boundaries
### Always
- API 改动同步 OpenAPI schema
### Never
- 不要在路由里写复杂业务逻辑（抽到 services/）
docs/AGENTS.md
# Docs
继承根目录。本子项目额外的：
## 写作规范
- 中文为主
- 代码示例必须能跑
- API 文档跟代码同步（每次 API 改动同步更新）
## Boundaries
### Always
- 改文档前先看 frontend/backend 实际实现
### Never
- 不要写 "to be added"，要么有内容，要么先不放
怎么用这些模板
- 找最像你项目的模板
- 复制到
项目根目录/AGENTS.md - 改
[填空]部分 - 让 Codex 帮你"扫一遍项目，告诉我哪些规则跟实际不符"
- 调整到一致
- commit 进 git
之后每次项目有重要变化（新技术、新规范、新边界），随手更新 AGENTS.md。
记住：AGENTS.md 是"活文档"，不是"一次性写完不再改"的东西。