code-taste git:20261030.b0ab227A

Immutable. This exact content never changes and is served at /api/v1/blob/189ba6463bdbd7cc.

---
name: code-taste
description: "Use when writing, modifying, refactoring, or reviewing software code; designing models, module boundaries, interfaces, or names; or writing README, AGENTS.md, design documents, and technical blog posts. Includes Go, Python, and TypeScript conventions. Skip read-only debugging, triage, call-path inspection, and operational execution; apply when the task moves into code changes."
---

# Code Taste

个人代码品味：从项目的业务架构、系统架构和应用架构理解问题，判断缺了什么，再安排改动。重点约束**判断力**而不是语法风格。

## 先建立全局视角，再决定改动落点

根据问题范围，选用三个互补的视角。以下是本 skill 的工作定义：

- **业务架构：核心概念 + 关系 + 串起概念的主流程。**判断当前问题是已有模型下的实现细节，还是暴露了概念缺失、职责混淆或流程缺口。
- **系统架构（System Architecture）：应用、服务与外部依赖的边界和协作。**判断职责与数据由谁拥有、通信契约是否充分、一致性与失败恢复由谁负责。具体见 [跨服务的职责与协作](references/modularity.md#跨服务的职责与协作)。
- **应用架构（Application Architecture）：单个应用或服务内部的模块、分层、接口与依赖。**结合入口、Service / Biz、Repository、DAO / Infra 等现有布局与 CQRS 的 Command / Query 职责，判断哪一层的契约或能力不足、哪些职责放错了位置。具体见 [按职责分派改动](references/modularity.md#按职责分派改动)。

从原始需求出发，用 [绿地视角](references/evolution.md#绿地视角) 检验现有抽象；已有方法和调用关系是现状证据，不直接限定方案边界。再将必要调整落到现有布局，不仅根据报错文件或性能热点决定修复位置。

三个视角用于定位问题，下面的 T0 / T1 / T2 用于控制分析深度。局部改动只需理解相关概念、流程与职责；配置值、格式等机械改动可以直接处理，不要求每次重画架构或输出设计报告。

## 适用范围

**用本 skill**：编写新代码 / 涉及结构判断的补丁 / 重构；做方案设计、模块拆分、接口设计；review 代码、评估坏味道、判断是否该抽象；定期回看近期 merged MR / 提交序列，识别补丁背后反复缺失的概念（自底向上迭代，沉淀进 `references/examples/`，一案例一文件）。

**先别来本 skill**：

- 核心是“为什么坏了 / 哪里报错 / 线上现象怎么定位” → 使用项目对应的 debugging / trace 能力，证据不足时不要先下结构结论。
- 核心是“要不要新增功能、功能怎么设计”且需求还没稳 → 先澄清原始需求和约束。
- 已有明确设计 / 计划 → 本 skill 只检查复杂度和边界，不替代执行型 skill。

## 按语义变化控制设计深度

三个架构视角回答“哪里需要判断”，T0 / T1 / T2 回答“现有设计需要改变到什么程度”。从业务模型、系统协作和应用内部职责定位问题，再按所需的设计变化确定深度。

| 档 | 判断依据 | 分析深度 |
|----|----------|----------|
| **T0 机械改动** | 不引入新的设计决策，业务模型、系统协作与应用内部职责均不变，例如格式、文案或保持语义的机械重命名 | 直接处理并做相应验证，检查表达准确性及已有契约是否保持，不展开架构分析 |
| **T1 既有设计内的调整** | 现有概念、职责与关键 contract 能自然承接需求；在其内部补齐行为、实现能力或局部组织，也可新增局部类型与辅助接口 | 理解相关概念、流程及 owner，完成必要的局部设计与 [代码 review](references/review.md#代码评审流程)，验证实现正确兑现既有设计 |
| **T2 设计调整** | 至少一个视角下的关键设计需要变化：业务概念或流程契约、服务 ownership 或协作协议、应用内部职责边界或依赖方向 | 展开受影响的模型、边界与 contract，比较主要方案；先做 [架构 review](references/review.md#架构评审)，再验证实现 |

定档不由行数、文件数、服务数或是否新增类型决定。保持语义的跨文件 rename 可以是 T0；跨服务补齐既定协议的实现可以是 T1；单个应用内重新分配 Repository 与 Biz 的职责也可以是 T2。配置或版本修改仍需根据实际行为与兼容性影响判断，不自动归为 T0。

定档随证据修正：起初像局部 bug，发现缺少业务概念或关键契约时升级；确认现有设计充分、只是实现未遵守时，按 T1 收敛。T2 也只展开相关设计，不要求每次重新设计整个系统。

意图标记也随档位增量判断：T0 通常不新增，但不能让已有 mark 与代码失真；T1 的 bugfix、行为分支和
局部契约变化检查 `spec` / `why` / `rule`；T2 的接口、模型和边界变化检查 `spec` / `why` / `ideal` /
`rule` / `link`。涉及临时措施时检查 `tmp`，只有具体验证场景值得长期寻址或复用时才补 `case`。
详细判断见 [结构化意图标记](references/mark.md)。

## 按问题读取

按当前缺口选读，不要求每次加载全部原则。详细问题入口见 [理念索引](references/README.md)。

| 当前判断 | 阅读 |
|---|---|
| 核心概念、关系与流程是否充分，是否需要新概念 | [模型：业务概念、关系与流程](references/modeling.md) |
| 服务边界、数据归属、通信与恢复责任是否合理 | [跨服务的职责与协作](references/modularity.md#跨服务的职责与协作) |
| 应用内部哪层职责、契约或能力不足，代码如何组织 | [模块化：边界、分层与协作](references/modularity.md) |
| 如何检验现有设计、比较差距并增量调整，或复盘 MR | [演进：绿地审视与增量调整](references/evolution.md) |
| 既定职责下，控制流与行为是否正确清楚 | [行为：控制流、职责与契约](references/behavior.md) |
| 命名、README / AGENTS.md、设计文档、Blog、注释与日志如何表达设计 | [表达：命名、文档、注释与日志](references/expression.md) |
| 检查架构或实现是否成立 | [评审：架构与代码](references/review.md) |

- 编写或修改 Go、Python、TypeScript：读取 [语言专项约定入口](references/language/README.md) 及对应语言文件；语言基线不改变 T0 / T1 / T2 定档。
- 涉及行为契约、领域不变量或非显而易见的设计理由：读取 [结构化意图标记](references/mark.md)。
- 查阅或沉淀反例与正例：见 [案例索引](references/examples/README.md)，一案例一文件。

## 设计判断的出发点

从原始问题、需求和约束出发控制复杂度；按本次改动的分析深度厘清模型、边界和命名，再进入实现细节。

开工前，以有独立判断的协作者身份，通过关键提问和必要的资料阅读，与用户厘清目标、约束、边界和完成标准。提问不仅补齐信息，也要帮助用户审视假设、明确取舍；有不同判断时，说明依据。等整体脉络清晰后，给出与任务复杂度匹配的方案。

把用户也视为重要的信息源。对目标、背景、约束或取舍有疑问时，主动向用户求证，不要默默猜测后继续推进；能自行查明的事实先查，仍会影响行动方向的不确定点及时提出。

## 输出约定

- 设计类：先输出问题模型、边界、关键取舍，再给建议方案；不要一上来铺实现细节
- review 类：findings first，按严重度或破坏性排序，摘要放后面；T2 先做架构 review，再做代码 review
- 重构类：先说明哪些逻辑应归并、迁移或拆分，以及如何降低理解和修改成本，再进入代码修改
- T0 机械改动的回答保持简洁，不把结果写成架构评审报告
- 如果给出结论，必须能落到模型、边界、依赖、命名或日志上下文中的至少一个具体点
- 设计 / 方案 review 按“原始需求 → 主要备选 → 选择及原因 → 主要改动 → 对既有设计的影响”组织。
- 涉及行为或结构变化时，交付说明本次新增、更新或无需更新意图标记的判断。

## 需要复核的信号

- 用技术实现名替代业务概念，例如 `xxxMap`、`manager`、`processor`
- Request/DTO/ORM 对象直接穿透到核心业务层
- 一个函数同时混合业务规则、流程控制、协议细节和持久化细节
- 为了复用而抽象，结果抽出一个接口复杂、语义模糊的浅模块
- 没先搜一下就当场手写一套系统里已存在的能力（base64 编解码、None 安全访问、分页、HTTP client、时间解析…），仓库因此沉淀出多套近似实现
- 错误信息只说失败，不说哪个参数、什么值、在做什么操作