系统化摸底任意代码库acquire-codebase-knowledge 的 Inquiry Checkpoints 分领域调查指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot在接入一个陌生代码库时最大的风险不是信息不足而是信息不可靠——README 描述的是理想架构而非现状、package.json里堆满了与生产无关的开发依赖、dist/产物里混入了大量误导性的模式。本篇文章以 awesome-copilot 仓库中 acquire-codebase-knowledge 技能内置的 inquiry-checkpoints.md 为核心骨架逐条拆解面向七类代码库文档STACK / STRUCTURE / ARCHITECTURE / CONVENTIONS / INTEGRATIONS / TESTING / CONCERNS的调查检查点并对照技能自带的 scan.py 扫描脚本实现讲清楚每个问题该看什么文件、为什么这么问、底层证据从哪来。读完你将掌握一套可复制、可验证的代码库调研方法论并能直接指挥 Copilot 快速产出证据可追溯的代码库文档。一、Inquiry Checkpoints 在整个技能工作流中的定位acquire-codebase-knowledge技能的目标是在docs/codebase/下产出七个文件STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md。整个执行流程被拆成四个阶段见 SKILL.md- [ ] Phase 1: Run scan, read intent documents - [ ] Phase 2: Investigate each documentation area - [ ] Phase 3: Populate all seven docs in docs/codebase/ - [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] itemsinquiry-checkpoints.md正是Phase 2 的专用调查清单。文档开篇明确说明其定位这是Per-template investigation questions要求先看扫描输出scan output找答案再读取源码填补缺口look for answers in the scan output first, then read source files to fill gaps。也就是说它是一份提问提纲而非答案模板——每个问题都指向一个具体的证据来源回答过程本身就是证据收集过程。这与 SKILL.md 中定义的输出契约强绑定每个论断必须可追溯到源文件、配置或终端输出未知项标记为[TODO]依赖团队意图的决策标记为[ASK USER]每份文档必须包含带具体文件路径的 evidence 清单。因此下面的每个检查点都可以理解为一条需要被证据回答的断言。二、STACK.md技术栈调查检查点技术栈是代码库文档的第一份产物也是最容易被表面印象误导的部分。检查点要求从五个维度逐一确认主语言与精确版本——检查.nvmrc、go.mod、pyproject.toml、DockerFROM行。版本号必须以这些文件为准而不是凭文件后缀猜测。包管理器——npm、yarn、pnpm、go mod、pip、uv等决定锁文件类型与安装/构建命令。核心运行时框架——Web 服务器、ORM、依赖注入容器等真正在生产路径上的框架。dependencies与devDependencies的区分——前者是生产依赖后者只是开发工具链。Docker 镜像及基础镜像——若有容器化FROM行直接暴露运行时版本。package.json/Makefile/pyproject.toml中的关键脚本——这些脚本是构建、测试、lint 的入口。底层实现scan.py 的清单式探测inquiry-checkpoints.md中的问题在 scan.py 里都有对应的自动化实现。脚本内置了覆盖 25 语言生态的MANIFESTS清单从 Node.js 的package.json、Python 的requirements.txt/pyproject.toml、Go 的go.mod、Rust 的Cargo.toml到 Java 的pom.xml/build.gradle、.NET 的*.csproj/*.sln、Ruby 的Gemfile、Elixir 的mix.exs乃至 Swift、Scala、Haskell、OCaml、Nim、Crystal、Julia 等生态的清单文件都被纳入。每个清单文件会以最多 80 行MANIFEST_PREVIEW_LINES的内容预览输出供 Phase 2 直接使用。当清单存在歧义时多个 manifest、陌生扩展名、没有package.json技能会加载配套的 stack-detection.md。这份参考文档提供了三层兜底推理清单文件 → 生态映射表如pyproject.toml属于 poetry/uv/hatch、语言运行时版本定位表Node 看.nvmrc或engines.nodePython 看[requires-python]Go 看go.mod首行、以及框架识别表如express/fastify/next/nestjs/core分别对应何种框架Python 侧fastapi/flask/django/sqlalchemy等。如果连 manifest 都没有还可以通过Dockerfile的FROM行反推运行时FROM node:X→ Node.js XFROM mcr.microsoft.com/dotnet/aspnet:X→ .NET X。最终这些证据被整理进 STACK.md 模板 的五个必需小节Runtime Summary语言/运行时/包管理器/构建系统四行表格、生产框架依赖表只列框架、数据、传输、认证等高影响依赖、开发工具链表、关键命令块、环境与配置说明——每一行都要求带 Evidence 文件路径。三、STRUCTURE.md目录布局调查检查点目录结构决定了读者理解整个项目的第一视角。检查点聚焦六个问题源码位置——通常在src/、lib/Go 项目则在根目录。入口点——查package.json的main与scripts.start、cmd/main.go、app.py。每个顶层目录的既定用途——需要从文件内容反推而不是照抄目录名。非显而易见的目录——如eng/、platform/、infra/这类目录往往藏着工程基础设施。隐藏配置目录——.github/、.vscode/、.husky/等影响 CI、编辑器与 Git 钩子行为。目录命名约定——camelCase、kebab-case、按领域还是按层组织。底层实现目录树、入口点与 monorepo 探测scan.py 的get_directory_tree()生成最大深度 3 层的目录树TREE_MAX_DEPTH 3最多 200 条记录并会跳过EXCLUDE_DIRS中定义的大量噪音目录L33-L38node_modules、.git、dist、build、out、.next、.nuxt、__pycache__、target、vendor、coverage等一律不进入扫描结果。入口点检测由ENTRY_CANDIDATESL88-L126驱动覆盖了各语言最常见的入口文件名TypeScript/JavaScript 的src/index.ts、src/main.ts、src/app.tsGo 的main.go、cmd/*/main.goPython 的main.py、app.py、cli.py.NET 的Program.csJava 的Application.javaRust 的src/main.rs等。monorepo 探测L152-L153按顺序检查pnpm-workspace.yaml、lerna.json、nx.json、turbo.json、rush.json、moon.yml以及packages/、apps/、libs/、services/等子包目录和package.json的workspaces字段。这与 SKILL.md 中的 Gotchas 提醒一致根package.json可能没有任何源码每个 workspace 可能有独立的依赖与约定需要在STACK.md中分别映射每个子包并在STRUCTURE.md中标注 monorepo 结构。四、ARCHITECTURE.md架构模式调查检查点架构描述最忌讳看图说话。检查点要求用证据回答五类问题组织方式——按层controllers → services → repos还是按特性组织这决定了依赖方向。主数据流——追踪一个请求或命令从入口到数据存储的完整路径。单例、依赖注入与显式初始化顺序——存在哪些全局状态启动顺序是否有硬性要求。后台 worker、队列或事件驱动组件——异步边界在哪里。重复出现的设计模式——Factory、Repository、Decorator、Strategy 等。与模板的衔接从问题到成文ARCHITECTURE.md 模板 把这组问题落成四个必需小节Architectural Style主风格 证据支撑的分类理由 2~3 条塑造设计的主要约束、System Flow用[entry] - [processing] - [domain logic] - [data/integration] - [response/output]形式描述 4~6 步数据流、Layer/Module Responsibilities 表每个层拥有什么、绝不能拥有什么、证据文件、Reused Patterns 表。其中Layer or module 拥有什么 / 绝不能拥有什么的设计正是为了强制区分代码里真实存在的边界与文档作者想象中的边界。数据流追踪可以充分利用 scan.py 的辅助输出入口点列表帮助定位请求起点目录树帮助识别层与模块的位置ENTRY_CANDIDATES中的src/server.ts与cmd/main.go等线索则指向进程的启动路径。检查点中是否有 worker/队列与 scan.py 的PERFORMANCE_MARKERS探测benchmark、k6.js、locustfile 等可以交叉印证异步或负载敏感组件的存在。五、CONVENTIONS.md编码规范调查检查点编码规范是文档中最容易被想当然的部分。检查点给出的七个问题全部要求看真实文件文件命名约定——抽查 10 个文件确认 camelCase、kebab-case 还是 PascalCase。函数与变量命名约定。私有方法/字段前缀——如_methodName、#field。linter 与 formatter 配置——检查.eslintrc、.prettierrc、golangci.yml。TypeScript 严格性设置——strict、noImplicitAny等。各层错误处理方式——throw 异常还是返回结构化错误对象。日志库与日志消息格式、import 组织方式barrel exports、路径别名、分组规则。底层实现lint 配置的自动发现scan.py 的LINT_FILES清单自动检测这些配置文件JavaScript/TypeScript 生态的.eslintrc*与eslint.config.js/mjs/cjs、.prettierrc*与prettier.config.*、.editorconfig、tsconfig*.jsonGo 的.golangci.yml/.yamlPython 的.flake8、.pylintrc、mypy.ini、setup.cfgRuby 的.rubocop.ymlPHP 的phpcs.xml/phpstan.neon以及新生态的biome.json。这些检测结果直接对应检查点第 4 条linter 和 formatter 配置。命名约定与错误处理策略没有自动化手段只能靠抽查源码——这正是检查点要求检查 10 个文件的原因少量样本无法得出可靠结论。错误处理判断需要结合层的位置入口层抛异常 vs. 数据层返回结构化错误这也是 Phase 2 与 Phase 3 需要人工交叉核对的部分。六、INTEGRATIONS.md外部服务调查检查点外部集成是安全与可靠性风险最集中的区域。检查点要求回答调用了哪些外部 API——搜索axios.、fetch(、http.Get(以及常量中的 base URL。凭据如何存储与访问——.env、secrets manager、环境变量。连接了哪些数据库——检查 manifest 中的pg、mongoose、prisma、typeorm、sqlalchemy。是否存在 API 网关、服务网格或代理。使用了哪些监控/可观测性工具——APM、Prometheus、日志管道。是否存在消息队列或事件总线——Kafka、RabbitMQ、SQS、Pub/Sub。底层实现凭据模板与安全配置探测scan.py 从两个角度辅助这组问题。一是环境变量模板检测L141扫描.env.example、.env.template、.env.sample、.env.defaults、.env.local.example并输出内容预览——因为密钥永远不会被提交.env.example是发现必填环境变量的最可靠来源。二是SECURITY_CONFIGS探测L175-L179.snyk、SECURITY.md、.dependabot.yml、sbom.json等文件的存在与否能侧面反映项目的安全合规姿态。数据库推断在检查点中被明确要求看 manifest 而非变量名——SKILL.md 的反模式表专门列了一条Guess the database from a variable name likedbUrl 是错误做法正确做法是检查 manifest 中是否出现pg、mysql2、mongoose、prisma等依赖。这与 stack-detection.md 的框架识别表一致mongoose→ MongoDB ODM、prisma→ 类型安全 ORM需检查prisma/schema.prisma、typeorm→ 装饰器风格 SQL ORM、sqlalchemy→ Python SQL ORM检查是否有alembic迁移。七、TESTING.md测试体系调查检查点测试文档的价值在于回答我改了代码怎么验证。检查点覆盖测试运行器——检查package.json的scripts.test、pytest.ini、go test。测试文件位置——与源码同目录、tests/还是__tests__/。断言库——Jest expect、Chai、pytest assert。外部依赖的 mock 方式——jest.mock、依赖注入、fixtures。集成测试打真实服务与单元测试用 mock的分布。是否强制覆盖率阈值——检查jest.config.js、.nycrc、pyproject.toml。底层实现测试与生产的边界TESTING.md 模板 把这些问题组织为五个小节测试栈与命令、测试布局、测试范围矩阵Unit/Integration/E2E、Mock 与隔离策略、覆盖率与质量信号。其中测试范围矩阵用 Covered? / Typical target / Notes 三列来明确哪些范围有真实测试覆盖。一个重要的实现细节是 scan.py 对测试目录的特殊处理TODO 搜索L290-L320会在遍历时剔除test、tests、__tests__、spec、__mocks__、fixtures目录并只统计SOURCE_EXTS中的源码扩展名。这意味着扫描输出中的 TODO/FIXME/HACK 是生产代码的债务信号——与检查点第 7 条CONCERNS配合时必须区分测试里的 TODO 是覆盖率缺口不是生产债务SKILL.md Gotchas 明确强调这一点。八、CONCERNS.md已知问题调查检查点这是七份文档中唯一以找茬为目的的模板检查点要求用扫描输出回答生产代码中的 TODO/FIXME/HACK 数量——见扫描输出。最近 90 天 git churn 最高的文件——见扫描输出。是否存在超过 500 行、混杂多种职责的文件。是否存在可并行化的串行调用。硬编码值——URL、ID、魔法数字是否应该抽成配置。安全风险——缺失输入校验、向客户端暴露原始错误信息、缺失认证检查。不随规模扩展的性能模式——N1 查询、多实例部署下的进程内缓存。底层实现churn 统计与代码度量这组问题中前两条有直接自动化支撑。get_git_churn() 执行git log --since90 days ago --name-only统计每个文件在 90 天内的改动次数并输出 Top 20——与检查点high churn fragile areas的判断直接对应。collect_code_metrics() 则输出总文件数、各语言文件数、总代码行数以及按体积排序的 Top 10 最大文件后者正是发现超 500 行混杂文件检查点第 3 条的起点。安全风险检查点第 6 条需要结合源码人工排查但 CONCERNS.md 模板 提供了结构化输出Top Risks 表严重级/证据/影响/建议动作、技术债务表、Security Concerns 表含 OWASP 类别列、性能与扩展性表、Fragile/High-Churn 区域表最后是必须存在的[ASK USER]编号问题清单——凡是需要团队意图才能判断的事项例如这个魔法数字是不是业务策略一律显式标记不许猜测。九、用 Checkpoints 驱动 Phase 4 验证循环inquiry-checkpoints.md的用途不止于 Phase 2 的调查它同时是 Phase 4 验证的基准见 SKILL.md用这份检查点逐条校验七个文档对每个非平凡论断确认至少存在一条证据引用任何必需章节缺失或缺乏支撑就修复文档并重新验证直到全部通过。验证通过标准也以检查点为参照没有无支撑的论断、没有空的必需章节、未知项用[TODO]而非假设、团队意图缺口显式标记[ASK USER]。也就是说这份清单同时承担了调查提纲和验收标准双重角色——每个检查点问题一旦被回答就应当能映射到最终文档中某一行带证据引用的内容。十、实战要点与常见误区必须避开的证据陷阱来自 SKILL.md GotchasMonorepos根package.json可能没有源码先检查workspaces、packages/、apps/每个 workspace 独立映射。过时 READMEREADME 描述的是想要的架构而非现状任何 README 论断都要与真实文件结构交叉验证后才可采信。TypeScript 路径别名tsconfig.json的paths配置会让/foo这类 import 无法直接映射到文件系统须先解析别名再记录结构stack-detection.md给出了/* → ./src/*的解析示例。生成/编译产物绝不以dist/、build/、generated/、.next/、out/、__pycache__/中的模式作为文档依据只记录源码约定。.env.example揭示必填配置密钥永不入库.env.example是发现必填环境变量的入口。devDependencies≠ 生产栈只有dependencies或 Poetry 等工具的等价节在生产运行linter/formatter/测试框架应单独记录为开发工具。测试里的 TODO ≠ 生产债务test/、tests/、spec/中的 TODO 是覆盖率缺口须在CONCERNS.md中与生产债务分开记录。高 churn 文件 脆弱区域git 历史中出现频率最高的文件改动率最高、隐含复杂度最高必须写入CONCERNS.md。反模式对照来自 SKILL.md❌ 不要✅ 应该目录中不存在 Domain/Data 层却写 Uses Clean Architecture with Domain/Data layers.只陈述目录结构真实呈现的内容未检查package.json就写 This is a Next.js project.先查dependencies再陈述实际存在的内容凭dbUrl这样的变量名猜测数据库检查 manifest 中的pg、mysql2、mongoose、prisma等把dist/、build/的命名模式记录为约定只看源码文件快速上手路径如果你想在自己或团队的项目中实践这套方法论完整闭环是# 1. 在目标项目根目录运行扫描脚本Python 3.8 与 git 为前置条件 python3 skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt # 2. 阅读扫描输出同时加载调查清单与兜底识别文档 # - skills/acquire-codebase-knowledge/references/inquiry-checkpoints.md # - skills/acquire-codebase-knowledge/references/stack-detection.md栈不明确时 # 3. 按顺序填充七份模板到 docs/codebase/ # - skills/acquire-codebase-knowledge/assets/templates/STACK.md # - skills/acquire-codebase-knowledge/assets/templates/STRUCTURE.md # - skills/acquire-codebase-knowledge/assets/templates/ARCHITECTURE.md # - skills/acquire-codebase-knowledge/assets/templates/CONVENTIONS.md # - skills/acquire-codebase-knowledge/assets/templates/INTEGRATIONS.md # - skills/acquire-codebase-knowledge/assets/templates/TESTING.md # - skills/acquire-codebase-knowledge/assets/templates/CONCERNS.md # 4. 用检查点逐条验证直到无无支撑论断、无空必需章节、未知用 [TODO]、意图缺口用 [ASK USER]这套工作流最核心的纪律只有一条文档里写的每一个字都要能在仓库里找到一个文件作为证人。扫描脚本负责自动收集证人inquiry-checkpoints.md负责保证每个领域都问到了正确的问题模板负责把答案组织成可检索、可引用的结构——三者合起来就是一份既快又不失真的代码库认知获取方案。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 系统化摸底任意代码库：acquire-codebase-knowledge 的 Inquiry Checkpoints 分领域调查指南
系统化摸底任意代码库acquire-codebase-knowledge 的 Inquiry Checkpoints 分领域调查指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot在接入一个陌生代码库时最大的风险不是信息不足而是信息不可靠——README 描述的是理想架构而非现状、package.json里堆满了与生产无关的开发依赖、dist/产物里混入了大量误导性的模式。本篇文章以 awesome-copilot 仓库中 acquire-codebase-knowledge 技能内置的 inquiry-checkpoints.md 为核心骨架逐条拆解面向七类代码库文档STACK / STRUCTURE / ARCHITECTURE / CONVENTIONS / INTEGRATIONS / TESTING / CONCERNS的调查检查点并对照技能自带的 scan.py 扫描脚本实现讲清楚每个问题该看什么文件、为什么这么问、底层证据从哪来。读完你将掌握一套可复制、可验证的代码库调研方法论并能直接指挥 Copilot 快速产出证据可追溯的代码库文档。一、Inquiry Checkpoints 在整个技能工作流中的定位acquire-codebase-knowledge技能的目标是在docs/codebase/下产出七个文件STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md。整个执行流程被拆成四个阶段见 SKILL.md- [ ] Phase 1: Run scan, read intent documents - [ ] Phase 2: Investigate each documentation area - [ ] Phase 3: Populate all seven docs in docs/codebase/ - [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] itemsinquiry-checkpoints.md正是Phase 2 的专用调查清单。文档开篇明确说明其定位这是Per-template investigation questions要求先看扫描输出scan output找答案再读取源码填补缺口look for answers in the scan output first, then read source files to fill gaps。也就是说它是一份提问提纲而非答案模板——每个问题都指向一个具体的证据来源回答过程本身就是证据收集过程。这与 SKILL.md 中定义的输出契约强绑定每个论断必须可追溯到源文件、配置或终端输出未知项标记为[TODO]依赖团队意图的决策标记为[ASK USER]每份文档必须包含带具体文件路径的 evidence 清单。因此下面的每个检查点都可以理解为一条需要被证据回答的断言。二、STACK.md技术栈调查检查点技术栈是代码库文档的第一份产物也是最容易被表面印象误导的部分。检查点要求从五个维度逐一确认主语言与精确版本——检查.nvmrc、go.mod、pyproject.toml、DockerFROM行。版本号必须以这些文件为准而不是凭文件后缀猜测。包管理器——npm、yarn、pnpm、go mod、pip、uv等决定锁文件类型与安装/构建命令。核心运行时框架——Web 服务器、ORM、依赖注入容器等真正在生产路径上的框架。dependencies与devDependencies的区分——前者是生产依赖后者只是开发工具链。Docker 镜像及基础镜像——若有容器化FROM行直接暴露运行时版本。package.json/Makefile/pyproject.toml中的关键脚本——这些脚本是构建、测试、lint 的入口。底层实现scan.py 的清单式探测inquiry-checkpoints.md中的问题在 scan.py 里都有对应的自动化实现。脚本内置了覆盖 25 语言生态的MANIFESTS清单从 Node.js 的package.json、Python 的requirements.txt/pyproject.toml、Go 的go.mod、Rust 的Cargo.toml到 Java 的pom.xml/build.gradle、.NET 的*.csproj/*.sln、Ruby 的Gemfile、Elixir 的mix.exs乃至 Swift、Scala、Haskell、OCaml、Nim、Crystal、Julia 等生态的清单文件都被纳入。每个清单文件会以最多 80 行MANIFEST_PREVIEW_LINES的内容预览输出供 Phase 2 直接使用。当清单存在歧义时多个 manifest、陌生扩展名、没有package.json技能会加载配套的 stack-detection.md。这份参考文档提供了三层兜底推理清单文件 → 生态映射表如pyproject.toml属于 poetry/uv/hatch、语言运行时版本定位表Node 看.nvmrc或engines.nodePython 看[requires-python]Go 看go.mod首行、以及框架识别表如express/fastify/next/nestjs/core分别对应何种框架Python 侧fastapi/flask/django/sqlalchemy等。如果连 manifest 都没有还可以通过Dockerfile的FROM行反推运行时FROM node:X→ Node.js XFROM mcr.microsoft.com/dotnet/aspnet:X→ .NET X。最终这些证据被整理进 STACK.md 模板 的五个必需小节Runtime Summary语言/运行时/包管理器/构建系统四行表格、生产框架依赖表只列框架、数据、传输、认证等高影响依赖、开发工具链表、关键命令块、环境与配置说明——每一行都要求带 Evidence 文件路径。三、STRUCTURE.md目录布局调查检查点目录结构决定了读者理解整个项目的第一视角。检查点聚焦六个问题源码位置——通常在src/、lib/Go 项目则在根目录。入口点——查package.json的main与scripts.start、cmd/main.go、app.py。每个顶层目录的既定用途——需要从文件内容反推而不是照抄目录名。非显而易见的目录——如eng/、platform/、infra/这类目录往往藏着工程基础设施。隐藏配置目录——.github/、.vscode/、.husky/等影响 CI、编辑器与 Git 钩子行为。目录命名约定——camelCase、kebab-case、按领域还是按层组织。底层实现目录树、入口点与 monorepo 探测scan.py 的get_directory_tree()生成最大深度 3 层的目录树TREE_MAX_DEPTH 3最多 200 条记录并会跳过EXCLUDE_DIRS中定义的大量噪音目录L33-L38node_modules、.git、dist、build、out、.next、.nuxt、__pycache__、target、vendor、coverage等一律不进入扫描结果。入口点检测由ENTRY_CANDIDATESL88-L126驱动覆盖了各语言最常见的入口文件名TypeScript/JavaScript 的src/index.ts、src/main.ts、src/app.tsGo 的main.go、cmd/*/main.goPython 的main.py、app.py、cli.py.NET 的Program.csJava 的Application.javaRust 的src/main.rs等。monorepo 探测L152-L153按顺序检查pnpm-workspace.yaml、lerna.json、nx.json、turbo.json、rush.json、moon.yml以及packages/、apps/、libs/、services/等子包目录和package.json的workspaces字段。这与 SKILL.md 中的 Gotchas 提醒一致根package.json可能没有任何源码每个 workspace 可能有独立的依赖与约定需要在STACK.md中分别映射每个子包并在STRUCTURE.md中标注 monorepo 结构。四、ARCHITECTURE.md架构模式调查检查点架构描述最忌讳看图说话。检查点要求用证据回答五类问题组织方式——按层controllers → services → repos还是按特性组织这决定了依赖方向。主数据流——追踪一个请求或命令从入口到数据存储的完整路径。单例、依赖注入与显式初始化顺序——存在哪些全局状态启动顺序是否有硬性要求。后台 worker、队列或事件驱动组件——异步边界在哪里。重复出现的设计模式——Factory、Repository、Decorator、Strategy 等。与模板的衔接从问题到成文ARCHITECTURE.md 模板 把这组问题落成四个必需小节Architectural Style主风格 证据支撑的分类理由 2~3 条塑造设计的主要约束、System Flow用[entry] - [processing] - [domain logic] - [data/integration] - [response/output]形式描述 4~6 步数据流、Layer/Module Responsibilities 表每个层拥有什么、绝不能拥有什么、证据文件、Reused Patterns 表。其中Layer or module 拥有什么 / 绝不能拥有什么的设计正是为了强制区分代码里真实存在的边界与文档作者想象中的边界。数据流追踪可以充分利用 scan.py 的辅助输出入口点列表帮助定位请求起点目录树帮助识别层与模块的位置ENTRY_CANDIDATES中的src/server.ts与cmd/main.go等线索则指向进程的启动路径。检查点中是否有 worker/队列与 scan.py 的PERFORMANCE_MARKERS探测benchmark、k6.js、locustfile 等可以交叉印证异步或负载敏感组件的存在。五、CONVENTIONS.md编码规范调查检查点编码规范是文档中最容易被想当然的部分。检查点给出的七个问题全部要求看真实文件文件命名约定——抽查 10 个文件确认 camelCase、kebab-case 还是 PascalCase。函数与变量命名约定。私有方法/字段前缀——如_methodName、#field。linter 与 formatter 配置——检查.eslintrc、.prettierrc、golangci.yml。TypeScript 严格性设置——strict、noImplicitAny等。各层错误处理方式——throw 异常还是返回结构化错误对象。日志库与日志消息格式、import 组织方式barrel exports、路径别名、分组规则。底层实现lint 配置的自动发现scan.py 的LINT_FILES清单自动检测这些配置文件JavaScript/TypeScript 生态的.eslintrc*与eslint.config.js/mjs/cjs、.prettierrc*与prettier.config.*、.editorconfig、tsconfig*.jsonGo 的.golangci.yml/.yamlPython 的.flake8、.pylintrc、mypy.ini、setup.cfgRuby 的.rubocop.ymlPHP 的phpcs.xml/phpstan.neon以及新生态的biome.json。这些检测结果直接对应检查点第 4 条linter 和 formatter 配置。命名约定与错误处理策略没有自动化手段只能靠抽查源码——这正是检查点要求检查 10 个文件的原因少量样本无法得出可靠结论。错误处理判断需要结合层的位置入口层抛异常 vs. 数据层返回结构化错误这也是 Phase 2 与 Phase 3 需要人工交叉核对的部分。六、INTEGRATIONS.md外部服务调查检查点外部集成是安全与可靠性风险最集中的区域。检查点要求回答调用了哪些外部 API——搜索axios.、fetch(、http.Get(以及常量中的 base URL。凭据如何存储与访问——.env、secrets manager、环境变量。连接了哪些数据库——检查 manifest 中的pg、mongoose、prisma、typeorm、sqlalchemy。是否存在 API 网关、服务网格或代理。使用了哪些监控/可观测性工具——APM、Prometheus、日志管道。是否存在消息队列或事件总线——Kafka、RabbitMQ、SQS、Pub/Sub。底层实现凭据模板与安全配置探测scan.py 从两个角度辅助这组问题。一是环境变量模板检测L141扫描.env.example、.env.template、.env.sample、.env.defaults、.env.local.example并输出内容预览——因为密钥永远不会被提交.env.example是发现必填环境变量的最可靠来源。二是SECURITY_CONFIGS探测L175-L179.snyk、SECURITY.md、.dependabot.yml、sbom.json等文件的存在与否能侧面反映项目的安全合规姿态。数据库推断在检查点中被明确要求看 manifest 而非变量名——SKILL.md 的反模式表专门列了一条Guess the database from a variable name likedbUrl 是错误做法正确做法是检查 manifest 中是否出现pg、mysql2、mongoose、prisma等依赖。这与 stack-detection.md 的框架识别表一致mongoose→ MongoDB ODM、prisma→ 类型安全 ORM需检查prisma/schema.prisma、typeorm→ 装饰器风格 SQL ORM、sqlalchemy→ Python SQL ORM检查是否有alembic迁移。七、TESTING.md测试体系调查检查点测试文档的价值在于回答我改了代码怎么验证。检查点覆盖测试运行器——检查package.json的scripts.test、pytest.ini、go test。测试文件位置——与源码同目录、tests/还是__tests__/。断言库——Jest expect、Chai、pytest assert。外部依赖的 mock 方式——jest.mock、依赖注入、fixtures。集成测试打真实服务与单元测试用 mock的分布。是否强制覆盖率阈值——检查jest.config.js、.nycrc、pyproject.toml。底层实现测试与生产的边界TESTING.md 模板 把这些问题组织为五个小节测试栈与命令、测试布局、测试范围矩阵Unit/Integration/E2E、Mock 与隔离策略、覆盖率与质量信号。其中测试范围矩阵用 Covered? / Typical target / Notes 三列来明确哪些范围有真实测试覆盖。一个重要的实现细节是 scan.py 对测试目录的特殊处理TODO 搜索L290-L320会在遍历时剔除test、tests、__tests__、spec、__mocks__、fixtures目录并只统计SOURCE_EXTS中的源码扩展名。这意味着扫描输出中的 TODO/FIXME/HACK 是生产代码的债务信号——与检查点第 7 条CONCERNS配合时必须区分测试里的 TODO 是覆盖率缺口不是生产债务SKILL.md Gotchas 明确强调这一点。八、CONCERNS.md已知问题调查检查点这是七份文档中唯一以找茬为目的的模板检查点要求用扫描输出回答生产代码中的 TODO/FIXME/HACK 数量——见扫描输出。最近 90 天 git churn 最高的文件——见扫描输出。是否存在超过 500 行、混杂多种职责的文件。是否存在可并行化的串行调用。硬编码值——URL、ID、魔法数字是否应该抽成配置。安全风险——缺失输入校验、向客户端暴露原始错误信息、缺失认证检查。不随规模扩展的性能模式——N1 查询、多实例部署下的进程内缓存。底层实现churn 统计与代码度量这组问题中前两条有直接自动化支撑。get_git_churn() 执行git log --since90 days ago --name-only统计每个文件在 90 天内的改动次数并输出 Top 20——与检查点high churn fragile areas的判断直接对应。collect_code_metrics() 则输出总文件数、各语言文件数、总代码行数以及按体积排序的 Top 10 最大文件后者正是发现超 500 行混杂文件检查点第 3 条的起点。安全风险检查点第 6 条需要结合源码人工排查但 CONCERNS.md 模板 提供了结构化输出Top Risks 表严重级/证据/影响/建议动作、技术债务表、Security Concerns 表含 OWASP 类别列、性能与扩展性表、Fragile/High-Churn 区域表最后是必须存在的[ASK USER]编号问题清单——凡是需要团队意图才能判断的事项例如这个魔法数字是不是业务策略一律显式标记不许猜测。九、用 Checkpoints 驱动 Phase 4 验证循环inquiry-checkpoints.md的用途不止于 Phase 2 的调查它同时是 Phase 4 验证的基准见 SKILL.md用这份检查点逐条校验七个文档对每个非平凡论断确认至少存在一条证据引用任何必需章节缺失或缺乏支撑就修复文档并重新验证直到全部通过。验证通过标准也以检查点为参照没有无支撑的论断、没有空的必需章节、未知项用[TODO]而非假设、团队意图缺口显式标记[ASK USER]。也就是说这份清单同时承担了调查提纲和验收标准双重角色——每个检查点问题一旦被回答就应当能映射到最终文档中某一行带证据引用的内容。十、实战要点与常见误区必须避开的证据陷阱来自 SKILL.md GotchasMonorepos根package.json可能没有源码先检查workspaces、packages/、apps/每个 workspace 独立映射。过时 READMEREADME 描述的是想要的架构而非现状任何 README 论断都要与真实文件结构交叉验证后才可采信。TypeScript 路径别名tsconfig.json的paths配置会让/foo这类 import 无法直接映射到文件系统须先解析别名再记录结构stack-detection.md给出了/* → ./src/*的解析示例。生成/编译产物绝不以dist/、build/、generated/、.next/、out/、__pycache__/中的模式作为文档依据只记录源码约定。.env.example揭示必填配置密钥永不入库.env.example是发现必填环境变量的入口。devDependencies≠ 生产栈只有dependencies或 Poetry 等工具的等价节在生产运行linter/formatter/测试框架应单独记录为开发工具。测试里的 TODO ≠ 生产债务test/、tests/、spec/中的 TODO 是覆盖率缺口须在CONCERNS.md中与生产债务分开记录。高 churn 文件 脆弱区域git 历史中出现频率最高的文件改动率最高、隐含复杂度最高必须写入CONCERNS.md。反模式对照来自 SKILL.md❌ 不要✅ 应该目录中不存在 Domain/Data 层却写 Uses Clean Architecture with Domain/Data layers.只陈述目录结构真实呈现的内容未检查package.json就写 This is a Next.js project.先查dependencies再陈述实际存在的内容凭dbUrl这样的变量名猜测数据库检查 manifest 中的pg、mysql2、mongoose、prisma等把dist/、build/的命名模式记录为约定只看源码文件快速上手路径如果你想在自己或团队的项目中实践这套方法论完整闭环是# 1. 在目标项目根目录运行扫描脚本Python 3.8 与 git 为前置条件 python3 skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt # 2. 阅读扫描输出同时加载调查清单与兜底识别文档 # - skills/acquire-codebase-knowledge/references/inquiry-checkpoints.md # - skills/acquire-codebase-knowledge/references/stack-detection.md栈不明确时 # 3. 按顺序填充七份模板到 docs/codebase/ # - skills/acquire-codebase-knowledge/assets/templates/STACK.md # - skills/acquire-codebase-knowledge/assets/templates/STRUCTURE.md # - skills/acquire-codebase-knowledge/assets/templates/ARCHITECTURE.md # - skills/acquire-codebase-knowledge/assets/templates/CONVENTIONS.md # - skills/acquire-codebase-knowledge/assets/templates/INTEGRATIONS.md # - skills/acquire-codebase-knowledge/assets/templates/TESTING.md # - skills/acquire-codebase-knowledge/assets/templates/CONCERNS.md # 4. 用检查点逐条验证直到无无支撑论断、无空必需章节、未知用 [TODO]、意图缺口用 [ASK USER]这套工作流最核心的纪律只有一条文档里写的每一个字都要能在仓库里找到一个文件作为证人。扫描脚本负责自动收集证人inquiry-checkpoints.md负责保证每个领域都问到了正确的问题模板负责把答案组织成可检索、可引用的结构——三者合起来就是一份既快又不失真的代码库认知获取方案。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考