Conventions Prompt：让 AI 代码更改融入你的仓库

Source: Dev.to

问题

如果你曾让助手“只添加这个功能”，你就会体会到其中的痛苦：

• 它会添加一个你从未使用过的新文件夹结构。
• 它的代码格式几乎和你的仓库相同，但又不完全一样。
• 它会创造出你们团队有意避免的模式。

结果未必错误——只是陌生。陌生的代码成本高昂。

Source: …

解决方案：约定提示

约定提示（Conventions Prompt） 是一小段可复用的指令块，使每一次修改看起来都像是由在你的代码库中工作了数月的人编写的。

• 大多数助手擅长解决问题，却在匹配你的问题解决方式上表现平平。
• 你的仓库已经形成了一套文化（命名约定、错误处理规则、日志风格、首选库、“我们这里不这么做”的约束、架构边界）。
• 约定提示把这些文化集中在一个地方，并附加到每个请求上，充当 风格 + 架构合同。

编写方式

保持足够简短以便实际使用，同时要足够具体以防止偏离。目标 20–60 行，并分成若干章节：

1. 项目结构 – 文件夹、模块、边界。
2. 代码风格 – 导入、命名、TypeScript 设置、lint 规则。
3. 运行时约定 – 错误、日志、追踪、指标。
4. 测试期望 – 测试放置位置、使用的框架、需要 mock 的内容。
5. 输出格式 – 仅 diff、文件列表或步骤计划。

模板（复制并改写）

CONVENTIONS (read first, follow strictly)

Architecture
- Don’t introduce new top‑level folders.
- Keep business logic in /src/domain.
- Keep I/O (HTTP, DB) in /src/adapters.
- No cross‑imports from adapters → domain.

Code style
- TypeScript, ESM. Prefer named exports.
- Prefer early returns over nested ifs.
- Don’t change unrelated formatting.
- Use existing utilities instead of adding new helpers.

Errors & logging
- Never swallow errors.
- Throw AppError(code, message, cause?).
- Log with logger.info|warn|error({ ...context }, message).

Testing
- Use Vitest.
- Tests live next to files as *.test.ts.
- Prefer fakes over heavy mocks.

Output
- Provide:
  1) A brief plan (3–6 bullets)
  2) A unified diff only (no extra commentary)
- If any convention conflicts with the request, ask a clarifying question before editing.

最后一行是“破玻璃”条款，用来防止自信的错误。

挖掘已有约定

您不需要从头编写。可以从以下内容中提取：

• .editorconfig、eslint、prettier、ruff、go fmt 规则
• tsconfig.json（严格性、模块设置）
• 现有的端点/服务以寻找模式
• 测试布局和 mock 风格
• 最近的 PR 中审阅者喜欢的做法

仅记录那些反复出现的规则；它们能节省最多的审阅时间，例如：

• “不要添加新依赖。”
• “不要引入新的抽象层。”
• “不要重构无关的代码。”

示例代码片段

如果你的仓库有标准的错误处理模式，请包含一个简短的示例：

// Example error handling pattern
try {
  const user = await repo.getUser(id);
  if (!user) throw new AppError('NOT_FOUND', 'User not found');
  return user;
} catch (err) {
  logger.error({ err, id }, 'getUser failed');
  throw err;
}

助手会像人类一样复制此内容。

使用提示：示例请求

任务

• 添加 POST /api/projects/:id/archive，将项目标记为已归档并返回更新后的项目。
• 重用已有的 auth 中间件。
• 如果项目不存在，返回 404。
• 添加测试。

上下文

• 现有的项目路由位于 src/adapters/http/routes/projects.ts。
• 项目的领域逻辑位于 src/domain/projects/。

一个好的请求示例：

[Paste CONVENTIONS here]

Task
- Add POST /api/projects/:id/archive
- Reuse the existing auth middleware
- Return 404 if project doesn’t exist
- Add tests

约定加上这两个文件路径就足够了；无需长篇解释。

实用的提示存储方式

1. Snippet file 在你的编辑器中（最快）。
2. Repository file 类似 PROMPTS/conventions.md（最适合团队）。
3. Seed message 在你的助手工作区中（最适合重复会话）。

团队通常选择选项 2，以便像审查代码一样审查提示。

最小差异

如果你希望更改自然融合，请目标是小的差异：

• “将更改局限于尽可能少的文件。”
• “除非必要，避免移动代码。”
• “除非你修改了文件，否则不要重新排序导入。”

添加约束，例如：

• “在添加辅助函数之前，先搜索是否已有可用的并复用它。”
• “不要重新格式化无关的代码。”
• “除非 linter 要求，否则不要更改引号/分号。”

只请求差异；目标是让审阅者在约 2 分钟内快速浏览 PR。

结论

Conventions Prompt 并不是让助手更聪明；而是让它们的输出 可预测、可审查且兼容团队。

如果你这周只能做一件事：写一个约 30 行的 Conventions Prompt，并将其附加到接下来的五个编码任务中。你的未来的自己（以及审阅者）会注意到的。

— Nova