展开知识库目录
第一次打开陌生仓库，先找规则、入口、构建和测试命令
第一次读陌生仓库，先确认项目规则、工作区状态、启动与测试入口，再沿一个具体任务追到源文件，最后得到一张有路径和命令依据的项目地图。
先确认规则和已有改动，再让 Agent 解释项目
陌生仓库最危险的第一步不是“看不懂”，而是在没读规则、没看工作区状态时直接改文件。先确认当前目录、项目根目录和未提交改动；如果 Git 状态不可用，也要把这一点写进记录，不能假装已经核对差异。
Codex 会在开始工作前读取适用范围内的 AGENTS.md；其他工具还可能使用 CLAUDE.md、README 或贡献指南。规则文件只告诉你应该怎么工作，真正的启动、构建和测试命令仍要回到当前仓库的配置文件核对。
先找到规则、说明文件和项目清单
下面的命令都从仓库根目录运行，不会修改文件。PowerShell 示例适用于 Windows PowerShell 5.1 或 PowerShell 7；Bash 示例适用于 macOS/Linux。Git 或 rg 不存在时记录原始错误，不要把缺少命令误判成项目损坏。
根目录、Git 状态和关键文件
Get-Location Get-ChildItem -Force git status --short git log -5 --oneline rg --files -g "AGENTS.md" -g "AGENTS.override.md" -g "CLAUDE.md" -g "README*" -g "CONTRIBUTING*" -g "package.json" -g "pyproject.toml" -g "go.mod" -g "Makefile" -g "compose*.yml" -g "compose*.yaml"
根目录、Git 状态和关键文件
pwd ls -la git status --short git log -5 --oneline find . -maxdepth 3 -type f \( -name 'AGENTS.md' -o -name 'AGENTS.override.md' -o -name 'CLAUDE.md' -o -name 'README*' -o -name 'CONTRIBUTING*' -o -name 'package.json' -o -name 'pyproject.toml' -o -name 'go.mod' -o -name 'Makefile' -o -name 'compose*.yml' -o -name 'compose*.yaml' \) -not -path './.git/*' -not -path './node_modules/*'
Windows 没有安装 rg 时，可以先用 Get-ChildItem 找根目录文件，或让 Agent 使用现有文件搜索能力。不要为了侦察仓库临时安装依赖。
从项目清单读取命令，不按文件夹名称猜技术栈
先读 README 和贡献指南，再看项目清单里的 scripts、tasks 或 targets。只记录仓库真实声明的命令；没有 test 脚本时写“未找到”，不要补一个看起来合理的命令。
| 看到的文件 | 先看什么 | 可以确认什么 |
|---|---|---|
| package.json | scripts、packageManager、engines | Node 项目的启动、构建、测试命令和版本要求 |
| pyproject.toml | project、tool、依赖与测试配置 | Python 包信息、工具配置；运行方式仍需结合 README |
| go.mod | module 与 go 版本 | Go 模块名和最低语言版本 |
| Makefile | 目标名称和目标实际执行的命令 | 项目封装的构建、测试或生成入口 |
| compose.yaml / Dockerfile | 服务、端口、卷、健康检查和启动命令 | 容器运行关系；不能据此确认生产部署方式 |
| CI 配置 | 实际执行的安装、构建和测试步骤 | 团队持续验证哪些路径，以及本地命令是否还有遗漏 |
看到 dist、build、coverage 或生成的 HTML 时，先搜索生成脚本和文件头标记。确认内容源之前不要直接修改生成物。
不要平均阅读全仓库，只追这次任务经过的路径
- 01
从用户入口或报错开始
记录页面 URL、CLI 命令、接口路径、函数名或完整错误。优先搜索唯一文案和符号，不要从体积最大的文件开始读。
- 02
追到读取和处理位置
沿路由、调用或导入关系找到真正读取数据和执行业务逻辑的文件，记下每一跳的路径和符号。
- 03
区分内容源与生成物
确认内容来自源码、Markdown、结构化数据、数据库还是远程接口。生成目录、缓存和编译产物通常不是首选编辑点。
- 04
找到与任务最近的验证
从项目清单、CI 和测试目录里找目标测试。能启动项目时只运行现有命令并保存实际输出；缺依赖、凭证或服务时明确停止。
- 05
写清影响范围和未知项
列出可能修改的源文件、会重新生成的文件、相邻模块和不会触碰的目录。路径没有证据时标成未知，不要补全。
如果 Agent 只给一段目录概览，没有路径、符号或命令输出，它还没有真正读懂与当前任务相关的部分。
先让它交一张项目地图，再决定是否允许修改
这篇教程本来就是用编程 Agent 接手仓库，因此这里保留一段可复制任务；它只授权读取和运行低风险验证，不授权写文件、安装依赖或部署。
先让它交一张项目地图，再决定是否允许修改
先只读检查这个仓库，不要修改文件、安装依赖或执行部署。
我要解决的问题：{具体问题或报错}
当前允许你运行：{只读命令和已有验证命令}
请先提交一张项目地图：
- 规则：实际读取的规则文件及适用范围
- 工作区：Git 状态或无法读取状态的原始错误
- 入口：与问题直接相关的页面、命令、路由或函数
- 路径：入口 -> 读取位置 -> 处理逻辑 -> 输出
- 内容源：真正应该修改的源文件
- 生成物：不应直接手改的目录或文件
- 验证：仓库中真实存在的启动、构建和测试命令
- 风险与未知：现有改动、缺失依赖、凭证和未确认判断
每个结论附文件路径、符号或命令输出。无法确认就写“未知”。交付项目地图后停止，等我确认再编辑。