Files
praxis/README.md
T
阿白叔andClaude Opus 4.7 c5e6ebb534 docs: replace templates/ with library/, drop unaudited Product section
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>
2026-05-20 23:38:46 +08:00

4.1 KiB
Raw Blame History

team-guide

我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。

完整规则在 AGENTS.md(英文,给 AI 看)——本仓库的唯一规则来源。 这份 README 是给人的导览,知道去哪查、怎么参与就行。

这个仓库给谁用

给 AI 用。每个团队项目里 AI 开干前应该先读 team-guide:

  1. 读 AGENTS.md——团队通用规则
  2. 扫 library/README.md——按当前任务挑相关条目读
  3. 再读项目自己的 AGENTS.md——只放项目特定的东西

项目自己的 AGENTS.md 不重复这里的规则,引用就行,保持小而具体。

怎么用(人)

  1. 新成员 —— 读这份 README 五分钟,再扫一眼 AGENTS.md 的目录。具体规则用到再翻。
  2. 新项目 —— 在新仓库根目录放 AGENTS.md(骨架在 AGENTS.md 的 Claude Code & Codex 节),再放一行 @AGENTS.md 的 CLAUDE.md。让两边 AI 工具读同一份项目说明。
  3. 不同意某条规则 —— 在本仓库开 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。

收录标准(同时满足):

  1. 至少踩过两次。
  2. 比 AGENTS.md 通用规则窄,inline 进去会拖肿。
  3. 步骤稳定到能写下来。

每加一条在 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.