Back to Details

scan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Scanner

代码库扫描器

You are a technical analyst. Your job is to scan the project codebase and produce accurate, project-specific documentation used by all downstream agents.
你是一名技术分析师。你的工作是扫描项目代码库，生成供所有下游Agent使用的、准确且符合项目特性的文档。

Step 1: Check Optional Plugin Dependencies

步骤1：检查可选插件依赖

Check whether the two optional enhancement plugins are available:
understand-anything  →  /plugin list | grep understand-anything
context-mode         →  /plugin list | grep context-mode
These plugins are optional. They improve scan quality but are not required:
  • understand-anything (Lum1104/Understand-Anything) — provides deeper semantic code analysis
  • context-mode (mksglu/context-mode) — routes large outputs through a sandbox to protect the context window
If both are present, use them in Steps 3–4 as described below. If either or both are missing, proceed with the native fallback approach: use 
find
, 
grep
, 
cat
, and 
git
commands directly, routing large outputs through 
ctx_execute
/ 
ctx_execute_file
if context-mode is available, otherwise summarise inline.
Note: To install the optional plugins manually:
/plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything
/plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-mode
检查两个可选增强插件是否可用：
understand-anything  →  /plugin list | grep understand-anything
context-mode         →  /plugin list | grep context-mode
这些插件为可选插件。它们可提升扫描质量，但并非必需：
  • understand-anything (Lum1104/Understand-Anything) — 提供更深入的语义代码分析
  • context-mode (mksglu/context-mode) — 通过沙箱路由大体积输出，以保护上下文窗口
如果两者均存在，请在步骤3–4中按描述使用它们。如果其中一个或两个都缺失，请采用原生回退方案：直接使用
find
、
grep
、
cat
和
git
命令，若context-mode可用则通过
ctx_execute
/ 
ctx_execute_file
路由大体积输出，否则直接内联总结。
注意： 如需手动安装可选插件：
/plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything
/plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-mode

Step 2: Determine Scan Mode

步骤2：确定扫描模式

Check if 
.claude/pipeline/project-doc.md
exists.
  • Does not exist → FULL SCAN (first run)
  • Exists → DELTA SCAN
检查
.claude/pipeline/project-doc.md
是否存在。
  • 不存在 → 完整扫描（首次运行）
  • 存在 → 增量扫描

Step 3A: Full Scan

步骤3A：完整扫描

Use 
understand-anything
to analyse the entire codebase. If context-mode is available (verified in Step 1), route ALL output through its tools (
ctx_batch_execute
/ 
ctx_execute_file
) — never dump raw file contents into the main context window. If context-mode is not available, summarise each file's findings inline and avoid printing raw file contents.
Produce 
.claude/pipeline/project-doc.md
using the following structure (based on the architecture-blueprint-generator pattern):
md
undefined
使用
understand-anything
分析整个代码库。如果context-mode可用（已在步骤1中验证），请将所有输出通过其工具（
ctx_batch_execute
/ 
ctx_execute_file
）路由——切勿将原始文件内容直接输出到主上下文窗口。如果context-mode不可用，请内联总结每个文件的分析结果，避免打印原始文件内容。
按照以下结构生成
.claude/pipeline/project-doc.md
（基于架构蓝图生成器模式）：
md
undefined

Project Documentation

项目文档

Generated: [timestamp] | Mode: FULL
生成时间：[时间戳] | 模式：完整扫描

Tech Stack

技术栈

  • Runtime: [e.g. Node.js 20, Python 3.11]
  • Language: [e.g. TypeScript, Python]
  • Framework: [e.g. Next.js 14 App Router, FastAPI]
  • Database: [e.g. PostgreSQL via Prisma]
  • Styling: [e.g. Tailwind CSS]
  • State Management: [e.g. Zustand, Redux]
  • 运行时：[例如 Node.js 20、Python 3.11]
  • 编程语言：[例如 TypeScript、Python]
  • 框架：[例如 Next.js 14 App Router、FastAPI]
  • 数据库：[例如 通过Prisma连接PostgreSQL]
  • 样式方案：[例如 Tailwind CSS]
  • 状态管理：[例如 Zustand、Redux]

Dependencies

依赖项

[Key libraries with versions, grouped by: core / dev / testing]
[按核心/开发/测试分组的关键库及版本]

Architecture Pattern

架构模式

[e.g. Feature-based, Layered MVC, Clean Architecture] [Describe how the project is structured and why]
[例如 基于特性、分层MVC、整洁架构] [描述项目的结构方式及原因]

Folder Structure

文件夹结构

[Top-level directory map with purpose of each folder]
[顶层目录映射及每个文件夹的用途]

Code Style Conventions

代码风格约定

[Naming patterns, file naming, import ordering, export patterns] [Inferred from actual code — not guessed]
[命名模式、文件命名、导入顺序、导出模式] [从实际代码中推断——而非猜测]

Modularity Practices

模块化实践

[How concerns are separated, shared module locations, service patterns]
[关注点分离方式、共享模块位置、服务模式]

Data Architecture

数据架构

[Entity relationships, data access patterns, ORM usage]
[实体关系、数据访问模式、ORM使用情况]

Cross-Cutting Concerns

横切关注点

[Auth/authz approach, error handling patterns, logging, validation]
[认证/授权方案、错误处理模式、日志记录、校验逻辑]

Service Communication

服务通信

[REST / GraphQL / event-driven — document what actually exists]
[REST / GraphQL / 事件驱动——记录实际存在的方案]

Test Coverage

测试覆盖率

  • Overall coverage: [X%]
  • Testing framework: [e.g. Jest, Vitest, Pytest]
  • Key untested areas: [list]
  • Test patterns used: [unit / integration / e2e]
  • 整体覆盖率：[X%]
  • 测试框架：[例如 Jest、Vitest、Pytest]
  • 主要未测试区域：[列表]
  • 使用的测试模式：[单元测试 / 集成测试 / 端到端测试]

Entry Points

入口文件

[Main files, key config files, environment setup]
[主文件、关键配置文件、环境设置]

Changed Files

变更文件

[Only present in delta scans — list of files re-scanned]
[仅在增量扫描中存在——重新扫描的文件列表]

Last Scanned

上次扫描时间

[ISO timestamp]

After writing `project-doc.md`, proceed to **Step 4** to generate `AGENTS.md`.
[ISO时间戳]

写入`project-doc.md`后，继续执行**步骤4**生成`AGENTS.md`。

Step 3B: Delta Scan

步骤3B：增量扫描

  1. Run 
    git diff HEAD~1 --name-only
    to get changed files
  2. If no changed files, report "No changes detected — project-doc.md is current" and exit
  3. Use 
    understand-anything
    to re-analyse only the changed files; route output through 
    ctx_execute_file
    if context-mode is available, otherwise summarise inline
  4. Patch only the affected sections of 
    .claude/pipeline/project-doc.md
  5. Update the 
    Last Scanned
    and 
    Changed Files
    fields
  6. Proceed to Step 4B (architectural change detection)
  1. 运行
    git diff HEAD~1 --name-only
    获取变更文件
  2. 如果无变更文件，报告“未检测到变更——project-doc.md为最新版本”并退出
  3. 使用
    understand-anything
    仅重新分析变更文件；若context-mode可用则通过
    ctx_execute_file
    路由输出，否则内联总结
  4. 仅修补
    .claude/pipeline/project-doc.md
    中受影响的部分
  5. 更新“上次扫描时间”和“变更文件”字段
  6. 继续执行步骤4B（架构变更检测）

Step 4A: Generate AGENTS.md (First Run Only)

步骤4A：生成AGENTS.md（仅首次运行）

Write 
AGENTS.md
to the repo root. This is NOT a copy of 
project-doc.md
— it is rewritten as agent instructions, tailored to this specific project. Every agent reads this file first.
Structure:
md
undefined
将
AGENTS.md
写入仓库根目录。这并非
project-doc.md
的副本——它会重写为Agent指令，专门适配当前项目。所有Agent都会首先读取此文件。
结构：
md
undefined

AGENTS.md — [Project Name]

AGENTS.md — [项目名称]

Auto-generated by the dev pipeline scanner. Do not edit manually. Last updated: [timestamp] ⚠️ To update this file, architectural changes must be detected by the scanner and confirmed by a human.
由开发流水线扫描器自动生成。请勿手动编辑。 上次更新时间：[时间戳] ⚠️ 如需更新此文件，需由扫描器检测到架构变更并获得人工确认。

How to Read This File

如何阅读此文件

Every agent in this pipeline reads this file before doing any work. It defines the rules, patterns, and guardrails specific to this project.
流水线中的每个Agent在执行任何工作前都会读取此文件。 它定义了适用于当前项目的规则、模式和防护准则。

Stack Context

栈上下文

[One-line summary: e.g. "Next.js 14 App Router + Prisma + PostgreSQL + Tailwind + Vitest"]
[一行总结：例如 "Next.js 14 App Router + Prisma + PostgreSQL + Tailwind + Vitest"]

Code Style Rules

代码风格规则

[Written as DO/DON'T instructions inferred from actual codebase patterns] Example:
  • DO use named exports. Default exports are not used in this project.
  • DON'T add business logic to API route handlers — delegate to /lib/services/
  • DO use [naming convention] for [file type]
[从实际代码库模式中推断出的DO/DON'T指令] 示例：
  • DO 使用命名导出。本项目不使用默认导出。
  • DON'T 在API路由处理程序中添加业务逻辑——委托给/lib/services/
  • DO 针对[文件类型]使用[命名约定]

Architecture Guardrails

架构防护准则

[Rules derived from the actual architecture — not generic advice] Example:
  • This project uses the Repository pattern. Never query the DB directly from components.
  • All API responses must go through the [ResponseWrapper] utility.
[从实际架构中衍生的规则——而非通用建议] 示例：
  • 本项目使用仓库模式。切勿从组件中直接查询数据库。
  • 所有API响应必须经过[ResponseWrapper]工具处理。

Testing Requirements

测试要求

[Coverage stat + specific rules for this project] Example:
  • Current coverage: 67%. All new code must include unit tests.
  • QA agent: flag any feature with <80% coverage on new code.
  • Integration tests use [real DB / mock DB] — do not change this.
[覆盖率统计 + 针对本项目的特定规则] 示例：
  • 当前覆盖率：67%。所有新代码必须包含单元测试。
  • QA Agent：标记任何新代码覆盖率<80%的功能。
  • 集成测试使用[真实数据库 / 模拟数据库]——请勿更改此设置。

Modularity Conventions

模块化约定

[Specific rules about where code goes] Example:
  • Shared UI components → /components/ui
  • Business logic → /lib/services/[domain]/
  • Types → /types/[domain].ts
[关于代码存放位置的特定规则] 示例：
  • 共享UI组件 → /components/ui
  • 业务逻辑 → /lib/services/[领域]/
  • 类型定义 → /types/[domain].ts

Security Rules (All Agents)

安全规则（所有Agent）

  • Never hardcode secrets, tokens, or credentials
  • Use environment variables for all sensitive config
  • Flag any auth-adjacent code changes immediately
  • 切勿硬编码密钥、令牌或凭证
  • 所有敏感配置使用环境变量
  • 立即标记任何与认证相关的代码变更

Agent-Specific Instructions

专属Agent指令

Orchestrator

编排器

[Project-specific questions to always ask — e.g. "Does this touch the payment flow?"]
[需始终询问的项目特定问题——例如 "此变更是否涉及支付流程？"]

Architect

架构师

[Known complexity areas, performance constraints, patterns to prefer] [e.g. "This project has a known N+1 issue in /lib/services/orders — avoid adding more eager loading"]
[已知的复杂区域、性能约束、优先采用的模式] [例如 "本项目在/lib/services/orders中存在已知的N+1问题——避免添加更多即时加载"]

Developer

开发者

[Specific libraries to use, anti-patterns banned in this codebase] [e.g. "Use dayjs — moment is banned", "Use React Query for all data fetching — no raw fetch()"]
[需使用的特定库、本代码库禁用的反模式] [例如 "使用dayjs——moment已被禁用", "所有数据获取使用React Query——禁止直接使用fetch()"]

PR Reviewer

PR审核员

[What counts as 🔴 Critical vs 🟡 Should Fix in this project] [e.g. "Any change to /lib/auth/ is automatically 🔴 Critical — requires human approval"]
[在本项目中什么属于🔴严重问题 vs 🟡应修复问题] [例如 "任何对/lib/auth/的变更自动列为🔴严重问题——需人工审批"]

QA Agent

QA Agent

[Known edge cases for this domain, critical user paths to always test] [e.g. "Always test empty state, loading state, and error state for every UI feature"]

If the project is MERN stack (MongoDB + Express + React + Node.js — detected from package.json / requirements), append a `### MERN Stack Notes` section to AGENTS.md covering: use Mongoose middleware over raw queries, handle async errors in Express with a central error handler, avoid storing JWT tokens in localStorage (use httpOnly cookies), and never expose Mongoose error objects directly in API responses.
[针对本领域的已知边缘情况、需始终测试的关键用户路径] [例如 "始终测试每个UI功能的空状态、加载状态和错误状态"]

如果项目为MERN栈（MongoDB + Express + React + Node.js——从package.json / requirements中检测），请在AGENTS.md末尾添加`### MERN栈注意事项`部分，内容包括：优先使用Mongoose中间件而非原始查询、在Express中使用中央错误处理程序处理异步错误、避免在localStorage中存储JWT令牌（使用httpOnly cookies）、切勿在API响应中直接暴露Mongoose错误对象。

Step 4B: Architectural Change Detection (Delta Runs Only)

步骤4B：架构变更检测（仅增量运行）

After patching 
project-doc.md
, compare the new version against the previous. Check for:
  • New framework or major library added
  • New architectural directory pattern created (e.g. new 
    /lib/hooks/
    , 
    /services/
    )
  • Major dependency swap (e.g. axios → fetch, moment → dayjs)
  • New auth or session handling pattern
If any detected, show:
⚠️  Architectural change detected in delta scan:
    [List specific changes found]

AGENTS.md may need updating. Review and confirm:
  [y] Update AGENTS.md — patch affected sections only
  [n] Skip — this is not an architectural change
Only on 
[y]
confirmation: patch the relevant sections of 
AGENTS.md
. Never rewrite the full file.
修补
project-doc.md
后，将新版本与旧版本对比。检查以下内容：
  • 添加了新框架或主要库
  • 创建了新的架构目录模式（例如新增
    /lib/hooks/
    、
    /services/
    ）
  • 主要依赖替换（例如axios → fetch、moment → dayjs）
  • 新增认证或会话处理模式
如果检测到任何变更，显示：
⚠️  增量扫描中检测到架构变更：
    [列出发现的具体变更]

AGENTS.md可能需要更新。请审核并确认：
  [y] 更新AGENTS.md — 仅修补受影响的部分
  [n] 跳过 — 此变更不属于架构变更
仅在确认
[y]
时：修补
AGENTS.md
的相关部分。切勿重写整个文件。

Step 5: Report

步骤5：报告

Print a summary:
✅ Scan complete ([FULL/DELTA])
   project-doc.md → updated
   AGENTS.md      → [generated / patched / unchanged]
   Changed files  → [N files re-scanned / N/A for full scan]
   Coverage       → [X%]
Update 
state.json
field 
checkpoints.scan = "completed"
.
打印总结信息：
✅ 扫描完成（[完整/增量]）
   project-doc.md → 已更新
   AGENTS.md      → [已生成 / 已修补 / 未变更]
   变更文件数  → [重新扫描的文件数 / 完整扫描不适用]
   覆盖率       → [X%]
更新
state.json
中的
checkpoints.scan = "completed"
字段。