yuanlang12/openpipal/repo-onboarding

陌生仓库上手

目标两个：用最少的读取拿到能动手的信息；项目还没有入口文档时，给它留下一份每条命令都真跑过的 AGENTS.md。

先分清是哪一种情况

看系统提示词里的 <project_context>：

发现文档里写的命令实际跑不通：别默默改文档，也别默默换一条命令蒙混过去。直说"文档写的是 X，跑不通；实际能跑的是 Y，要我更新文档吗"。

定位：最多 10 个文件

按这个顺序读，够用就停，数到 10 必停：

1. ls 仓库根（一层，不递归）——先看有什么，再决定读什么
2. 包/构建清单：package.json / pyproject.toml / Cargo.toml / go.mod / Makefile——命令的真相在这里，不在 README
3. 锁文件只看文件名认包管理器（pnpm-lock.yaml / yarn.lock / package-lock.json / uv.lock），不读内容
4. CI 配置（.github/workflows/ 等）——项目真正跑的那套命令，通常比 README 新
5. README*——背景与"这是什么"；长就只读前 100 行
6. 挑一个测试文件 + 一个源码入口文件——认目录约定与代码风格
7. lint / 格式配置——只在这次要改代码风格时才读

还有疑问就问用户，别接着翻。跨子系统的大范围调研派 subagent，别把翻找过程堆进主上下文。

起草 AGENTS.md（只在"两个都没有"这一支）

每条命令先真跑一遍

写进去的每条命令都必须在这个仓库里真执行过。跑不通就换一条能跑通的，或者干脆不写这条。绝不把没跑过的命令写进文档——它会被之后每一个 AI 工具、每一次会话当成事实，错一条就一直错下去。

只跑读类命令：装依赖、测试、类型检查、构建、lint。脚本名里带 publish / deploy / release / migrate / clean 的一律只记录、不执行。整套测试可能很慢，跑之前先说一声。

形状

# 项目名
 
一两句：这是什么、给谁用。
 
## 常用命令
-安装：…
-测试：…
-类型检查 / lint：…
-构建：…
 
## 代码约定
只写从代码里读出来的、和工具默认不一样的那几条。
 
## 别碰
生成目录、迁移文件、凭证文件。

不写什么

• 不抄 package.json 一眼能看到的依赖清单
• 不写架构长文——那是 README 的事
• 不写"要写测试""注意代码质量"这类放之四海的话，模型本来就知道
• 不写署名、不写"由 XX 生成"——这份文件是给所有 AI 工具读的开放格式，署名既没用又占地方
• 不写这次任务的具体内容——那是会话，不是项目规矩

正文控制在 250–450 词（中文 400–700 字）以内。超了说明你在写 README。

写盘前先问

把草稿完整贴给用户看，说清两件事：写到哪个路径、哪几条命令是你真跑过的。用户同意了再 `write`——这是往人家的版本库里加文件。

用户想要一份不进版本库的私人规矩，写 AGENTS.override.md，并提醒他加进 .gitignore。

写完之后

• 本轮的 <project_context> 已经定型，新写的文档要下一个对话才会自动注入。这一轮按你自己刚写的那份办就行，不用假装读到了。
• 收尾说清：文件在哪、哪几条命令验证过、还有哪几条没验证。