pattern-matching

模式匹配

概述

每个代码库都有自己的风格印记。你的任务是精确复现这种印记，让评审者无法分辨原有代码与新增内容的界限。

核心原则： 先观察，再行动。你编写的每个函数、文件和文件夹，都必须能在代码库中找到现成的范例。如果你无法指出自己遵循的范例，就已经引入了偏差。

没有例外。没有变通。没有捷径。

首要准则

EVERY ADDITION MUST MIRROR AN EXISTING PRECEDENT

如果代码库偏好 snake_case，你就使用 snake_case。如果服务位于 src/domain/ 下，你的服务也放在那里。如果错误通过自定义的 Result<T> 类型传递，你就毫无疑问地采用它。这里没有个人偏好的余地。

适用场景

以下情况必须遵循：

• 修改现有代码库中的任何文件
• 在既定架构中引入新模块、路由或组件
• 为你并非始创的项目贡献功能
• 重构并调整现有逻辑

以下情况不必遵循：

• 从零搭建全新项目（参见 godmode:project-bootstrap）
• 编写永远不会纳入版本控制的一次性脚本

入门流程

BEFORE producing any code in an existing repository:

1. SURVEY: Locate 2-3 files or functions that solve a comparable problem
2. CATALOG: Record every convention they share
   - Identifier formatting (camelCase, snake_case, PascalCase)
   - Directory taxonomy (where do peers of this file reside?)
   - Import conventions (relative paths, aliases, barrel files)
   - Error propagation strategy (exceptions, Result types, error codes)
   - State access patterns (global store, context injection, parameter passing)
   - Test co-location and framework choices
3. REPLICATE: Produce your code using the identical conventions
4. AUDIT: Hold your output beside the originals — does it pass as native?

Omit any step = drift introduced

一致性的维度

文件级约定

BEFORE placing a new file:

1. Where do its siblings reside? (directory hierarchy)
2. How are filenames formed? (kebab-case.ts, PascalCase.tsx, snake_case.py)
3. What internal structure does each file follow? (imports, types, constants, logic, exports)
4. How are exports surfaced? (default export, named exports, re-export indexes)

函数级约定

BEFORE writing a new function, class, or component:

1. Identify an existing function that addresses a similar concern
2. Mirror its shape:
   - Argument style (destructured object vs positional args)
   - Return envelope (Promise<T>, Result<T, E>, nullable)
   - Error strategy (try/catch, .catch(), explicit error returns)
   - Observability (logger.info(), structured JSON, console methods)
   - Validation technique (Zod, Joi, manual guards, type narrowing)
3. Rely on the SAME libraries and utilities the project already depends on
   - Do not introduce ramda if the project uses native array methods
   - Do not pull in got if the project wraps fetch
   - Do not add a competing ORM when one is already wired in

架构级约定

BEFORE inserting a new module or layer:

1. How is the codebase stratified?
   - Routes -> Controllers -> Services -> Repositories?
   - Pages -> Components -> Hooks -> Helpers?
   - Handlers -> Domain -> Infrastructure?
2. Which way do imports flow?
3. Where does business logic concentrate?
4. How do cross-cutting concerns surface? (auth middleware, logging wrappers, error boundaries)

仿写方法

最快的保持一致之道：找到最相近的范例，并逐字逐句地仿照。

1. LOCATE: "Find the file most similar to what I need to create"
2. STUDY: Absorb its structure, imports, error handling, naming, export style
3. DUPLICATE: Use it as a skeleton
4. SPECIALIZE: Swap in only the logic unique to your feature
5. COMPARE: Place them side by side — can you spot the newcomer?

有效的提示词模式：

"Here is our existing payment service (src/services/payment.ts).
Produce the new subscription service using identical structure, patterns, and naming."

展示具体示例，始终胜过用文字描述规则。

常见偏差模式

AI 倾向	项目约定	修正方式
console.log()	通过 winston 实现结构化日志记录	采用项目的日志处理流程
通用的 try/catch	特定领域的 ServiceError 类	使用项目的错误层级来抛出和捕获错误
内联 Tailwind 类	CSS Modules / styled-components	遵循项目的样式方案
使用 axios 发送 HTTP 请求	lib/http 中自定义的 fetch 封装	使用团队构建的封装
新建辅助函数	utils/ 中现有的工具集	新建任何内容前先检查 utils/
扁平文件布局	按功能嵌套文件夹	遵循现有的目录结构蓝图
默认导出	全部使用命名导出	与代码库的导出约定保持一致
宽松的 any 类型	使用泛型的严格 TypeScript	遵循项目的类型规范
使用 let 声明	默认使用 const	沿用现有的变量声明习惯
原始 SQL 字符串	ORM 查询构建器	使用项目的数据访问层

提交前验证

最终确认前，请检查：

• 文件位于合适的目录中（与同类文件放在一起）
• 文件名遵循通行的命名规范
• 导入顺序和别名用法与既定风格一致
• 所有标识符（变量、函数、类型）都遵循现有命名规则
• 错误处理与代码库的标准模式一致
• 没有新增依赖来重复实现现有功能
• 测试遵循现有测试所用的框架、结构和命名规范
• 日志通过项目的日志记录器输出
• 代码读起来就像是原作者写的一样

认知陷阱

合理化说辞	事实
“我的方法客观上更好”	一致性胜过个人喜好。遵循代码库的做法。
“这是一种更现代的技术”	现代不代表适合这个代码库。与现有实际情况保持一致。
“这只是一个文件”	一个不一致的文件会为另外十个文件开先例。熵会不断累积。
“我之后会统一整理”	你不会这么做。不完整的迁移比统一沿用旧做法危害更大。
“当前模式有缺陷”	先与人沟通。禁止单方面更改约定。
“这个依赖显然更好”	单独来看更好，并不足以成为重复引入的理由。项目已经解决了这个问题。

防护规则

禁止的操作：

• 引入与现有依赖功能重叠的库
• 采用与代码库格格不入的命名约定
• 将文件放在不符合现有目录结构的位置
• 未经明确的人类批准就更改既定约定
• 编写在视觉上与相邻代码明显不同的代码

必须执行的操作：

• 动笔前检查 2-3 个类似文件
• 充分利用项目现有工具，再考虑发明新工具
• 原样复用错误处理、日志记录和验证模式
• 偏离现有做法前先征求许可（“代码库使用 X。要继续使用 X，还是迁移到 Y？”）

集成

互补技能：

• godmode:ux-patterns -- 将一致性应用于 UI 组件约定
• godmode:design-integration -- 将一致性应用于设计系统的使用
• godmode:quality-enforcement -- 通过自动化检查发现偏差

相邻技能：

• godmode:codebase-research -- 发现外部模式；此技能负责执行内部约定
• godmode:system-design -- 指导全新项目的结构；此技能规范既有代码库