one-way-door

单向门检查

有些决策很容易撤销：你可以更改 UI 组件、重命名变量，或替换实用函数，而不会造成长久影响。这些是双向门：走过去后，如果发现不对，还可以走回来。

另一些决策则会产生引力。一旦流量、用户或其他代码依赖它们，改变方向的代价就会很高。上线后的数据库架构迁移、外部使用者依赖的 API 契约、塑造整个权限模型的身份验证边界。这些都是单向门。

软件中代价最高的错误不是 Bug，而是仓促做出的不可逆架构决策。

检查内容

数据模型和数据库架构

匹配文件：schema.prisma、schema.graphql、*.sql、migration*、models.py、models.ts、entities.py、entities.ts

数据模型是最难撤销的决策。数据库一旦有了数据行，每次架构变更都需要迁移。重命名列会导致查询失效。关系变更会影响整个应用。

需要思考的问题：

• 你是否梳理了实体之间的所有关系？
• 这种架构能否支持所需查询，同时避免 N+1 问题？
• 这种规范化方式是否适合你的读写模式？

基础设施和部署配置

匹配文件：docker-compose*、Dockerfile、*.tf、terraform*、pulumi*、cdk*、cloudformation*、k8s*、kubernetes*、helm*

基础设施选择会限制其上构建的一切。从 ECS 切换到 Kubernetes，或从 Lambda 切换到容器，都会影响部署流水线、监控、扩缩容和团队知识储备。

需要思考的问题：

• 这是满足需求的最简单基础设施吗？
• 团队对这套技术栈有多少运维经验？
• 故障恢复方案是什么？

身份验证和授权

匹配文件：auth.{ts,js,py}、firestore.rules、storage.rules、*.rules、security.{ts,js,py,json,rules,yaml,yml}、rbac.{ts,js,py,json}、permissions.{ts,js,py,json}

这些匹配模式特意限定了扩展名：与此无关、仅包含 security 或 permissions 一词的文件（例如笔记、文档或测试）不会触发检查。

身份验证边界是承重墙。Session 与 JWT、基于角色与基于属性、单租户与多租户，每种选择都会塑造你的安全模型、用户体验和合规状况。

需要思考的问题：

• 这是否涵盖所有用户类型和访问模式？
• 你将如何处理令牌刷新、会话过期和撤销？
• 从一开始就要面向单租户还是多租户构建？

API 契约和服务接口

匹配文件：openapi*、swagger*、*.proto、*.graphql、api-schema*、routes.ts、routes.js、routes.py

已发布的 API 是对使用者的承诺。破坏性变更需要版本管理、弃用期和迁移指南。服务之间的内部 API 会造成难以解除的耦合。

需要思考的问题：

• 谁会使用此 API？内部服务、外部开发者，还是两者都有？
• 你将如何管理破坏性变更的版本？
• 你是否暴露了本应保留为私有的实现细节？

事件系统和消息总线

匹配文件：events.ts、eventbus.ts、eventemitter.py、eventhandler.py、pubsub*、queue*、kafka*、rabbit*

事件架构是生产者与消费者之间的契约。多个服务一旦订阅某个事件，变更其结构就需要协调部署。对事件顺序的假设会成为架构约束。

需要思考的问题：

• 你是否定义了事件架构，包括必填字段和可选字段？
• 消费者无法处理某个事件时会发生什么？
• 你是否需要顺序保证？

CI/CD 流水线

文件位于：.github/、.gitlab/、.circleci/，或名称匹配 Jenkinsfile、.travis.yml、cloudbuild*

CI/CD 流水线会成为发布流程的支柱。团队会围绕部署工作流形成肌肉记忆。更改流水线结构意味着需要重新培训，而过渡期间部署失败可能会阻碍整个团队。

需要提出的问题：

• 该流水线是否支持你的分支策略？
• 如果部署失败，回滚流程是什么？
• 密钥是否得到了安全处理？

依赖项和包配置

文件名匹配：package.json、Cargo.toml、go.mod、requirements.txt、pyproject.toml、Gemfile

框架和依赖项的选择会影响整个代码库。从 React 切换到 Vue，或从 Express 切换到 Fastify，都意味着需要重写应用的大部分内容。

需要提出的问题：

• 这个依赖项是否在积极维护？
• 它是否能满足你的规模要求？
• 如果需要切换，迁移路径是什么？

云服务配置

文件名匹配：firebase.json、.firebaserc、firestore.indexes*

云服务配置会让你受制于特定的提供商和架构。Firestore 索引决定查询性能。Firebase 规则定义了你的安全边界。

需要提出的问题：

• 你是否愿意长期使用这个提供商？
• 你是否针对实际查询模式测试过这些索引？
• 如果需要迁移，退出策略是什么？

双向门（可以自由选择的内容）

以下文件类型可以放心快速决策，并在之后更改：

• UI 组件、React/Vue/Svelte 组件、CSS、模板
• 实用函数、辅助函数、格式化程序、验证器
• 测试文件、测试基础设施可以自由重构
• 文档、README、指南、注释
• 日志和监控、日志格式、指标名称
• 配置文件、.env、功能标志、应用配置
• 静态资源、图片、字体、图标

强制允许列表

可选的 Claude Code hook 会在进行任何模式检查前先执行提前退出允许列表。即使文件名包含 auth 或 security 之类的词，测试、固定样本、模拟文件、Markdown，以及文档或计划文本文件也会通过。

共享技能不依赖此 hook。手动审查拟议文件时，也应应用相同的允许列表。

如何实施

共享项目指令

将此规则添加到项目的规范指令文件中。Codex 使用 AGENTS.md，Claude Code 使用 CLAUDE.md。如果其中一个文件导入另一个文件，请编辑规范文件。

### One-way door check

Before creating a file that represents an architectural decision, ask which
parts would be difficult to reverse. One-way doors include data models, service
communication patterns, authentication boundaries, tenancy models, and
infrastructure configuration. If a decision is a one-way door, ask the user and
wait for an explicit answer. Use the client's structured question tool when it
has one. Explain the trade-offs and at least two alternatives before asking
whether to proceed. Two-way doors, such as UI components, utilities, and
styling, can be changed quickly.

此手动工作流是可移植的行为方式。无需自动 hook 也能正常使用：

1. 在写入文件前，识别出这个单向门文件。
2. 说明哪些内容将变得难以撤销。
3. 至少提供两个备选方案，并说明各自的权衡。
4. 询问用户并等待明确答复。如果客户端提供结构化提问工具，请使用该工具。
5. 仅在用户批准具体决策后才写入。

可选的 Claude Code 强制执行

Claude Code 用户可以安装仓库的 one-way-door-check hook，以自动阻止写入前操作。该 hook 及其批准提示工具属于可选的 Claude Code 强制执行机制，并非共享 Agent Skills 行为。该适配器会维护一个作用域为会话的待处理与已批准记录，以便获批文件可重试而不陷入循环。

此技能目录中包含 PowerShell 移植版本 one-way-door-check.ps1 和 one-way-door-approve.ps1。hook 文档包含 POSIX 实现、记录规则以及 Claude Code 接线说明。没有此适配器的客户端必须使用上述手动工作流。不要将缺少自动强制执行视为已获批准。

三个问题

在做出任何不可逆的决定之前，先问自己：

1. 我承诺了什么？，这个决定会限制什么？哪些事情会变得更难更改？
2. **还有哪些替代方案？**有没有更简单的做法？有没有更容易撤销的做法？
3. **迁移路径是什么？**如果后来发现这个决定是错的，我们该如何改变方向？

如果你无法清楚地回答这些问题，那就还没准备好跨过这扇门。