2026Technology-Competition/AGENTS.md

开发范式：Stage-Driven Agent Development (SDAD)

阶段流程（必须严格遵守，不可跳过或合并）

① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证

强制规则

• 阶段顺序不可调换，每个阶段完成后才进入下一阶段
• Stage ④ 人类审批是必经门，未通过不得进入编码
• 编码过程中发现方案有遗漏/矛盾，先暂停提问，不自作主张

日志规则（自动执行）

每次创建或修改代码文件后，在项目根目录的 _AI_USAGE_LOG.md 中追加一条记录，必须包含以下字段：

• 日期时间：文件修改时间（用 Get-Item LastWriteTime 或 Get-Date 获取），不可乱填或估算
• 范式步骤：当前已完成的阶段累积链（如 ① 用户提出 → ② 需求澄清），按实际执行顺序
• 修改摘要：简要描述改了什么
• 中间产物：AI 交互过程中被淘汰的草稿或过程稿，包括但不限于：先给了伪代码后改正式实现、输出了多个方案选了其中一个、调试时生成的废弃代码版本、类型试错（如先用 typeof import() 后改 interface）、先改文件 A 后发现不够又改了文件 B
• 涉及文件：文件路径列表
• 使用模型：当前使用的模型名

排除项：打包工程（生产打包 VSIX，npm run package-prod / vsce package）不需要记录

阶段执行指引

• Stage ① @用户提出：load skill stage-1-propose
• Stage ② @需求澄清：load skill stage-2-clarify
• Stage ③ @方案设计：load skill stage-3-design
• Stage ④ @人类审批：load skill stage-4-approve
• Stage ⑤ @编码实现：load skill stage-5-implement
• Stage ⑥ @审查验证：load skill stage-6-verify

---

项目：vscode-code-reviewer

VSCode 代码审查与规范检查一体化插件。

开发者命令

命令	说明
npm run compile	TypeScript 编译（tsc -p ./）+ 拷贝 webview JS（scripts/copy-webview-js.mjs）
npm run compile:test	测试编译（tsc -p ./tsconfig.test.json）
npm run watch	tsc watch 模式
npm run lint	ESLint 检查 src/（eslint src）
npm test	测试编译 → 运行测试（compile:test && vscode-test）
npm run package-prod	生产打包 VSIX（scripts/package-prod.mjs）
F5 (VSCode)	启动 Extension Dev Host

测试运行器：@vscode/test-cli，配置在 .vscode-test.mjs，测试文件匹配 out/tests/**/*.test.js（测试源码位于根目录 tests/）。

验证顺序：lint → compile → npm test（npm test 内部执行 compile:test + vscode-test）。

架构

四层架构，见 docs/superpowers/specs/2026-07-10-code-reviewer-design.md：

UI 层 — Webview 审查/设置面板（src/panel、src/views）+ Inline Diagnostic + Code Action
核心层 — Orchestrator（编排器）+ Merger（合并）+ AI 审查引擎（src/ai）
适配层 — Linter 适配器（统一 LinterAdapter 接口，src/adapters/adapter.ts）
基础层 — 配置管理（src/config）/ 规则管理（src/rules）/ 报告导出（src/utils/report.ts）

所有 linter 统一实现 LinterAdapter 接口（定义在 src/adapters/adapter.ts），通过 Orchestrator 调度，结果合并后通过 Webview 面板展示。

文件结构

src/
├── extension.ts              # 入口：activate/deactivate
├── activation/               # 注册命令、视图、CodeAction
├── adapters/                 # LinterAdapter 接口 + 5 个 linter 适配器（ESLint/Stylelint/SQLFluff/PMD/JSP）
├── ai/                       # AI 审查引擎 + Provider 框架（providers/）
├── orchestrator/             # 编排器：调度适配器、聚合结果
├── merger/                   # 结果合并（静态诊断 + AI 翻译配对）
├── fix/                      # 修复链路（fixEngine/aiFixEngine/customFixEngine/fixPreview/fixPending 等）
├── rules/                    # 规则管理（builtin-rules、转换器/导入/导出/过滤/预览）
├── scope/                    # 方法级审查（method-extractor、status-cache）
├── panel/                    # 审查/设置 Webview 面板
├── views/                    # TreeView/CodeLens Provider + webview JS
├── config/                   # 配置管理（ai/linter/fixer/secret）
├── diagnostics/              # Inline Diagnostic 标记
├── i18n/                     # 多语言消息
├── jsp/                      # JSP 源码提取
├── services/                 # auxClasspath 等辅助服务
├── types.ts + types/         # 公共类型
└── utils/                    # 工具函数

命令 ID 前缀统一为 codeReviewer.（如 codeReviewer.review）。

代码规范

• 变量/函数：camelCase，类：PascalCase
• 导入风格：ESM（import/export）
• 不加注释
• 异步用 async/await
• ESLint 配置：eslint.config.mjs（typescript-eslint parser）

设计文档

设计 spec 存放路径：docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 编码须严格遵循已批准的 spec，不得自作主张。 非 spec 文档（如时间线、复盘类文档）放根目录 docs/。