team-guide is now positioned as the external rulebook agents read at project start: project AGENTS.md files reference team-guide rather than duplicating its content. - Delete templates/ (5 files). The only useful one — AGENTS.md skeleton — is now an inline code block in AGENTS.md §2. Handoff checklist also inlined into AGENTS.md §7. - Remove the unaudited "Product projects" section (was AGENTS.md §5). Project repos document their own release scheme in their own AGENTS.md. - Add library/ as a catalog for narrower specs. - Seed library/git-upload/SPEC.md: what to commit / what not to, .gitignore baseline, sensitive-info scan, leaked-secret recovery. - AGENTS.md gets a "How AI agents use this repo" intro and a §5 Team library section indexing library/. - README.md updated to match: explicit "for AI" framing, library section, drop product-spec mentions. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
4.1 KiB
team-guide
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
完整规则在 AGENTS.md(英文,给 AI 看)——本仓库的唯一规则来源。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
这个仓库给谁用
给 AI 用。每个团队项目里 AI 开干前应该先读 team-guide:
- 读
AGENTS.md——团队通用规则 - 扫
library/README.md——按当前任务挑相关条目读 - 再读项目自己的
AGENTS.md——只放项目特定的东西
项目自己的 AGENTS.md 不重复这里的规则,引用就行,保持小而具体。
怎么用(人)
- 新成员 —— 读这份 README 五分钟,再扫一眼 AGENTS.md 的目录。具体规则用到再翻。
- 新项目 —— 在新仓库根目录放
AGENTS.md(骨架在 AGENTS.md 的 Claude Code & Codex 节),再放一行@AGENTS.md的CLAUDE.md。让两边 AI 工具读同一份项目说明。 - 不同意某条规则 —— 在本仓库开 PR 改它,不要私下绕开。
语言策略
- 给人看的(中文):本 README。
- 给 AI 看的(英文):
AGENTS.md、CLAUDE.md、library/下所有内容。 - Git 元数据(英文):commit、PR 标题、分支名、tag 注释。
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
目录
team-guide/
├── README.md ← 你正在看(中文,给人)
├── AGENTS.md ← 全部团队规则(英文,给 AI)
├── CLAUDE.md ← 一行 @AGENTS.md import
└── library/ ← 窄主题专项规范目录
├── README.md ← catalog
└── git-upload/ ← 第一篇:什么该传什么不该传
└── SPEC.md
AGENTS.md 内含:
项目背景 · 编辑规则 · 语言策略 · Vibe coding · Claude Code & Codex 配置 ·
Git 工作流 · 代码与产出风格 · Team library 索引 · 规划节奏 · Handoff。
Library 怎么扩
碰到一个跨项目的具体话题、AGENTS.md 里塞进去会拖肿(比如"git 上传到底什么该传"、"PII 处理"、"eval 报告格式"),就在 library/ 下开一个子目录写 SPEC.md。
收录标准(同时满足):
- 至少踩过两次。
- 比 AGENTS.md 通用规则窄,inline 进去会拖肿。
- 步骤稳定到能写下来。
每加一条在 library/README.md 的 catalog 表里加一行"什么时候读它"。
版本管理
本仓库(规范类)按日期打 tag:YYYYMMDD,比如 20260520。同一天多次发布加 -N 后缀(20260520-2)。从 main 打 tag。
通用规则:
main永远是当前工作副本。- 只用 annotated tag(
git tag -a)。 - Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(
team-guide @ 20260520)就行。
项目仓库自己(task_assistant 这类)用各自的 tag 方案(通常是 semver vX.Y.Z),写在项目自己的 AGENTS.md 里。
具体命令和什么时候切 tag——见 AGENTS.md 的 Git workflow 节。
几条最容易踩的线(速查)
完整版在 AGENTS.md 和 library/,这里挑人最常忘的:
- 长 session 的上下文会污染输出,新任务开新 session
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
- AI 试同一个方案两次报同样的错——叫停,自己上
git add .前先git status看一眼,确认没有不该传的文件- 提交前
git diff --cached扫一眼;密钥误提交的应急流程在library/git-upload/SPEC.md
远端
git.simgreek.com/simgreek/team-guide · tags 列表
License
Internal.