---
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 等现有布局，判断哪一层的契约或能力不足、哪些职责放错了位置。具体见 [按职责分派改动](references/modularity.md#按职责分派改动)。

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

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

## 适用范围

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

**先别来本 skill**：

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

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

根据问题涉及的语义与职责确定分析深度，避免对琐碎改动过度设计；发现概念或边界缺口时再升级定档。

**定档**（决定起多少设计脑）：

| 档 | 什么改动 | 起多少 |
|----|----------|--------|
| **T0 琐碎** | 不涉及新的语义判断，主要是配置值、版本号、文案、格式或机械重命名等改动 | 不起设计脑，优先直接改；最多扫常驻项——命名是否表意、日志 / 错误是否带上下文 |
| **T1 局部** | 在既有大概念和边界内，调整行为，或设计 / 调整局部小概念、类型与流程 | 局部设计 + 代码 review——确认 owner 不变，再看正确性、可读性、命名、函数层级与日志（见 [代码 Review](references/review.md#代码评审流程)） |
| **T2 结构** | 改变顶层概念、owner、模块边界、依赖方向、跨边界契约或广泛引用的公共符号 | 完整设计脑——模型 / 边界 / 依赖 / 接口（从 [架构判断入口](references/README.md) 进入） |

> 档由改动的**语义变化与影响层级**决定，不由行数、文件数或是否新增类型决定：百行机械 rename 仍是
> T0；大概念内部新增私有类型或接口可以是 T1；5 行修改若改变跨边界契约也应是 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、时间解析…），仓库因此沉淀出多套近似实现
- 错误信息只说失败，不说哪个参数、什么值、在做什么操作