One-way door check

单向门决策检查

Some decisions are easy to reverse — you can change a UI component, rename a variable, or swap a utility function with no lasting consequences. These are two-way doors: walk through, and if it's wrong, walk back.

Other decisions create gravity. Once traffic, users, or other code depends on them, changing course gets expensive. A database schema migration after launch. An API contract that external consumers rely on. An auth boundary that shapes your entire permission model. These are one-way doors.

The most expensive mistakes in software aren't bugs. They're irreversible architectural decisions made too quickly.

有些决策很容易逆转——你可以更改UI组件、重命名变量或替换工具函数，不会产生持久影响。这些是双向门决策：走进去，如果发现错了，还可以退回来。

另一些决策则会产生“引力”。一旦有流量、用户或其他代码依赖它们，再改变方向就会付出高昂代价。比如上线后的数据库 schema 迁移、外部消费者依赖的API契约、影响整个权限模型的权限边界。这些是单向门决策。

软件中最昂贵的错误不是bug，而是过于仓促做出的不可逆架构决策。

What gets flagged

会被标记的文件类型

Data models and database schemas

数据模型与数据库Schema

Files matching:

schema.prisma

,

schema.graphql

,

*.sql

,

migration*

,

models.py

,

models.ts

,

entities.py

,

entities.ts

Data models are the hardest decisions to reverse. Once your database has rows, every schema change requires a migration. Column renames break queries. Relationship changes cascade through your entire application.

Questions to ask:

Have you mapped all the relationships between entities?
Will this schema support the queries you need without N+1 problems?
Are you normalizing appropriately for your read/write patterns?

匹配的文件：

schema.prisma

、

schema.graphql

、

*.sql

、

migration*

、

models.py

、

models.ts

、

entities.py

、

entities.ts

数据模型是最难逆转的决策。一旦数据库中有了数据，每次Schema变更都需要迁移。列重命名会破坏查询，关系变更会影响整个应用。

需要问的问题：

你是否梳理了所有实体之间的关系？
该Schema能否支持所需的查询，避免N+1问题？
你是否根据读写模式进行了合理的规范化设计？

Infrastructure and deployment configs

基础设施与部署配置

Files matching:

docker-compose*

,

Dockerfile

,

*.tf

,

terraform*

,

pulumi*

,

cdk*

,

cloudformation*

,

k8s*

,

kubernetes*

,

helm*

Infrastructure choices constrain everything built on top of them. Switching from ECS to Kubernetes, or from Lambda to containers, affects deployment pipelines, monitoring, scaling, and team knowledge.

Questions to ask:

Is this the simplest infrastructure that meets your needs?
What's your team's operational experience with this stack?
What does failure recovery look like?

匹配的文件：

docker-compose*

、

Dockerfile

、

*.tf

、

terraform*

、

pulumi*

、

cdk*

、

cloudformation*

、

k8s*

、

kubernetes*

、

helm*

基础设施的选择会限制其之上的所有构建工作。从ECS切换到Kubernetes，或从Lambda切换到容器，会影响部署流水线、监控、扩容和团队知识体系。

需要问的问题：

这是满足需求的最简基础设施方案吗？
你的团队对该技术栈有多少运维经验？
故障恢复流程是怎样的？

Authentication and authorization

身份认证与授权

Files matching:

auth.ts

,

auth.js

,

auth.py

,

firestore.rules

,

storage.rules

,

*.rules

,

rbac*

,

permissions*

,

security*

Auth boundaries are load-bearing walls. Session vs JWT, role-based vs attribute-based, single-tenant vs multi-tenant — each choice shapes your security model, user experience, and compliance posture.

Questions to ask:

Does this cover all your user types and access patterns?
How will you handle token refresh, session expiry, and revocation?
Are you building for single-tenant or multi-tenant from the start?

匹配的文件：

auth.ts

、

auth.js

、

auth.py

、

firestore.rules

、

storage.rules

、

*.rules

、

rbac*

、

permissions*

、

security*

权限边界是“承重墙”。Session vs JWT、基于角色 vs 基于属性、单租户 vs 多租户——每种选择都会影响你的安全模型、用户体验和合规性。

需要问的问题：

它是否覆盖了所有用户类型和访问模式？
你将如何处理令牌刷新、会话过期和吊销？
你从一开始就按单租户还是多租户模式构建？

API contracts and service interfaces

API契约与服务接口

Files matching:

openapi*

,

swagger*

,

*.proto

,

*.graphql

,

api-schema*

,

routes.ts

,

routes.js

,

routes.py

Published APIs are promises to consumers. Breaking changes require versioning, deprecation periods, and migration guides. Internal APIs between services create coupling that's hard to unwind.

Questions to ask:

Who will consume this API? Internal services, external developers, or both?
How will you version breaking changes?
Are you exposing implementation details that should stay private?

匹配的文件：

openapi*

、

swagger*

、

*.proto

、

*.graphql

、

api-schema*

、

routes.ts

、

routes.js

、

routes.py

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

需要问的问题：

谁会使用这个API？内部服务、外部开发者，还是两者都有？
你将如何对破坏性变更进行版本管理？
你是否暴露了应该保密的实现细节？

Event systems and message buses

事件系统与消息总线

Files matching:

events.ts

,

eventbus.ts

,

eventemitter.py

,

eventhandler.py

,

pubsub*

,

queue*

,

kafka*

,

rabbit*

Event schemas are contracts between producers and consumers. Once multiple services subscribe to an event, changing its shape requires coordinated deploys. Event ordering assumptions become architectural constraints.

Questions to ask:

Have you defined the event schema, including required vs optional fields?
What happens when a consumer fails to process an event?
Do you need ordering guarantees?

匹配的文件：

events.ts

、

eventbus.ts

、

eventemitter.py

、

eventhandler.py

、

pubsub*

、

queue*

、

kafka*

、

rabbit*

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

需要问的问题：

你是否定义了事件Schema，包括必填和可选字段？
当消费者处理事件失败时会发生什么？
你是否需要顺序保证？

CI/CD pipelines

CI/CD流水线

Files in:

.github/

,

.gitlab/

,

.circleci/

, or matching

Jenkinsfile

,

.travis.yml

,

cloudbuild*

CI/CD pipelines become the backbone of your release process. Teams build muscle memory around deploy workflows. Changing pipeline structure means retraining, and broken deploys during the transition can block your entire team.

Questions to ask:

Does this pipeline support your branching strategy?
What's the rollback procedure if a deploy fails?
Are secrets handled securely?

位于以下目录的文件：

.github/

、

.gitlab/

、

.circleci/

，或匹配

Jenkinsfile

、

.travis.yml

、

cloudbuild*

的文件

CI/CD流水线会成为发布流程的核心。团队会围绕部署工作流形成肌肉记忆。更改流水线结构意味着重新培训，过渡期间的部署故障可能会阻塞整个团队。

需要问的问题：

这个流水线是否支持你的分支策略？
如果部署失败，回滚流程是怎样的？
密钥是否得到安全处理？

Dependency and package configs

依赖与包配置

Files matching:

package.json

,

Cargo.toml

,

go.mod

,

requirements.txt

,

pyproject.toml

,

Gemfile

Framework and dependency choices ripple through your entire codebase. Switching from React to Vue, or from Express to Fastify, means rewriting large portions of your application.

Questions to ask:

Is this dependency actively maintained?
Does it handle your scale requirements?
What's the migration path if you need to switch?

匹配的文件：

package.json

、

Cargo.toml

、

go.mod

、

requirements.txt

、

pyproject.toml

、

Gemfile

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

需要问的问题：

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

Cloud service configs

云服务配置

Files matching:

firebase.json

,

.firebaserc

,

firestore.indexes*

Cloud service configs lock you into specific providers and architectures. Firestore indexes determine query performance. Firebase rules define your security boundary.

Questions to ask:

Are you comfortable with this provider for the long term?
Have you tested these indexes against your actual query patterns?
What's the exit strategy if you need to migrate?

匹配的文件：

firebase.json

、

.firebaserc

、

firestore.indexes*

云服务配置会将你锁定到特定的供应商和架构中。Firestore索引决定查询性能。Firebase规则定义你的安全边界。

需要问的问题：

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

Two-way doors (what passes through)

双向门决策（可直接通过）

These file types are safe to decide quickly and change later:

UI components — React/Vue/Svelte components, CSS, templates
Utility functions — Helpers, formatters, validators
Test files — Test infrastructure can be refactored freely
Documentation — README, guides, comments
Logging and monitoring — Log formats, metric names
Configuration files —
```
.env
```
, feature flags, app config
Static assets — Images, fonts, icons

以下文件类型可以快速决策并稍后更改：

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

How to implement

实现方法

Option 1: CLAUDE.md rule

选项1：CLAUDE.md规则

Add this to your project's

CLAUDE.md

:

markdown

undefined

将以下内容添加到项目的

CLAUDE.md

中：

markdown

undefined

One-way door check

Before creating new files that represent architectural decisions, ask: "Which of these decisions would be difficult to reverse?" One-way doors include data models, service communication patterns, auth boundaries, tenancy models, and infrastructure configs. These create gravity — once traffic, users, or other code depends on them, changing course gets expensive. If a decision is a one-way door, pause and discuss the trade-offs before committing. Two-way doors (UI components, utilities, styling) can be decided quickly and changed later.

undefined

Before creating new files that represent architectural decisions, ask: "Which of these decisions would be difficult to reverse?" One-way doors include data models, service communication patterns, auth boundaries, tenancy models, and infrastructure configs. These create gravity — once traffic, users, or other code depends on them, changing course gets expensive. If a decision is a one-way door, pause and discuss the trade-offs before committing. Two-way doors (UI components, utilities, styling) can be decided quickly and changed later.

undefined

Option 2: PreToolUse hook (automated enforcement)

选项2：PreToolUse钩子（自动化执行）

Add this to your Claude Code

settings.json

:

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/one-way-door-check.sh"
          }
        ]
      }
    ]
  }
}

将以下内容添加到Claude Code的

settings.json

中：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/one-way-door-check.sh"
          }
        ]
      }
    ]
  }
}

The hook script

钩子脚本

bash

#!/bin/sh

bash

#!/bin/sh

One-way door check hook (PreToolUse:Write)

Flags architectural decisions that are hard to reverse.

INPUT=$(cat) [ -z "$INPUT" ] && exit 0

Extract the file path from tool_input

FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\s*:\s*"[^"]"' | head -1 | sed 's/."file_path"\s*:\s*"//;s/"//') [ -z "$FILE_PATH" ] && exit 0

FILENAME=$(basename "$FILE_PATH") FILENAME_LOWER=$(echo "$FILENAME" | tr "[:upper:]" "[:lower:]") DIR=$(dirname "$FILE_PATH")

ONE_WAY=0 REASON=""

FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\s*:\s*"[^"]"' | head -1 | sed 's/."file_path"\s*:\s*"//;s/"//') [ -z "$FILE_PATH" ] && exit 0

FILENAME=$(basename "$FILE_PATH") FILENAME_LOWER=$(echo "$FILENAME" | tr "[:upper:]" "[:lower:]") DIR=$(dirname "$FILE_PATH")

ONE_WAY=0 REASON=""

Database schemas and migrations

if echo "$FILENAME_LOWER" | grep -qE "schema.(prisma|graphql|sql)|migration|.sql$|models?.(py|ts|js)$|entities?.(py|ts|js)$"; then ONE_WAY=1 REASON="data model / database schema" fi

Infrastructure and deployment configs

Authentication and authorization

API contracts and service interfaces

Event systems and message queues

Package manager configs (dependency choices)

Firebase and cloud service configs

if echo "$FILENAME_LOWER" | grep -qE "^firebase.json$|^.firebaserc$|firestore.indexes"; then ONE_WAY=1 REASON="cloud service config (Firebase)" fi

CI/CD pipelines

if echo "$DIR" | grep -qE ".(github|gitlab|circleci)" || echo "$FILENAME_LOWER" | grep -qE "^(jenkinsfile|.travis.yml|cloudbuild)"; then ONE_WAY=1 REASON="CI/CD pipeline" fi

if [ "$ONE_WAY" = "1" ]; then cat >&2 <<HOOK_MSG ONE_WAY_DOOR: You tried to create $FILENAME ($REASON). This write has been blocked because it is a one-way door -- a decision that becomes hard to reverse once other code, data, or users depend on it.

REQUIRED ACTION: You MUST use the AskUserQuestion tool before retrying this write. Present the user with:

What this file does and why it is a one-way door
At least 2 alternative approaches (if any exist) with their trade-offs
An option to proceed as planned

Frame the question around the specific architectural decision, not just "should I create this file?" The user needs to understand what they are committing to.

After the user responds, proceed according to their choice. HOOK_MSG exit 2 fi

exit 0


**How it works:**

1. The hook intercepts every `Write` tool call (new file creation)
2. It extracts the file path and checks it against known one-way-door patterns
3. If the file matches, the hook exits with code 2 (block) and sends a message to stderr
4. Claude receives the block message and must use `AskUserQuestion` to discuss the decision with the user
5. Two-way door files pass through silently (exit 0)

**Exit codes:**
- `0` — Allow (two-way door, proceed normally)
- `2` — Block (one-way door, requires discussion)

if echo "$DIR" | grep -qE ".(github|gitlab|circleci)" || echo "$FILENAME_LOWER" | grep -qE "^(jenkinsfile|.travis.yml|cloudbuild)"; then ONE_WAY=1 REASON="CI/CD pipeline" fi

if [ "$ONE_WAY" = "1" ]; then cat >&2 <<HOOK_MSG ONE_WAY_DOOR: You tried to create $FILENAME ($REASON). This write has been blocked because it is a one-way door -- a decision that becomes hard to reverse once other code, data, or users depend on it.

REQUIRED ACTION: You MUST use the AskUserQuestion tool before retrying this write. Present the user with:

What this file does and why it is a one-way door
At least 2 alternative approaches (if any exist) with their trade-offs
An option to proceed as planned

Frame the question around the specific architectural decision, not just "should I create this file?" The user needs to understand what they are committing to.

After the user responds, proceed according to their choice. HOOK_MSG exit 2 fi

exit 0


**工作原理：**

1. 钩子会拦截每个`Write`工具调用（新文件创建操作）
2. 提取文件路径并与已知的单向门决策文件模式进行匹配
3. 如果文件匹配，钩子会以代码2退出（阻止操作）并向stderr发送消息
4. Claude会收到阻止消息，必须使用`AskUserQuestion`工具与用户讨论该决策
5. 双向门决策文件会直接通过（以代码0退出）

**退出代码：**
- `0`——允许（双向门决策，正常执行）
- `2`——阻止（单向门决策，需要讨论）

The three questions

三个关键问题

Before committing to any one-way door, ask:

What am I committing to? — What does this decision constrain? What becomes harder to change?
What are the alternatives? — Is there a simpler approach? A more reversible one?
What's the migration path? — If this turns out to be wrong, how do we change course?

If you can't answer these questions clearly, you're not ready to walk through the door.

在做出任何单向门决策之前，问自己：

我在承诺什么？——这个决策会限制什么？什么会变得更难更改？
有哪些替代方案？——有没有更简单的方法？更可逆的方法？
迁移路径是什么？——如果这个决策被证明是错误的，我们如何转向？

如果你无法清晰回答这些问题，说明你还没准备好做出这个决策。

one-way-door

Original

Translation

One-way door check

单向门决策检查

What gets flagged

会被标记的文件类型

Data models and database schemas

数据模型与数据库Schema

Infrastructure and deployment configs

基础设施与部署配置

Authentication and authorization

身份认证与授权

API contracts and service interfaces

API契约与服务接口

Event systems and message buses

事件系统与消息总线

CI/CD pipelines

CI/CD流水线

Dependency and package configs

依赖与包配置

Cloud service configs

云服务配置

Two-way doors (what passes through)

双向门决策（可直接通过）

How to implement

实现方法

Option 1: CLAUDE.md rule

选项1：CLAUDE.md规则

One-way door check

One-way door check

Option 2: PreToolUse hook (automated enforcement)

选项2：PreToolUse钩子（自动化执行）

The hook script

钩子脚本

One-way door check hook (PreToolUse:Write)

One-way door check hook (PreToolUse:Write)

Flags architectural decisions that are hard to reverse.

Flags architectural decisions that are hard to reverse.

Extract the file path from tool_input

Extract the file path from tool_input

Database schemas and migrations

Database schemas and migrations

Infrastructure and deployment configs

Infrastructure and deployment configs

Authentication and authorization

Authentication and authorization

API contracts and service interfaces

API contracts and service interfaces

Event systems and message queues

Event systems and message queues

Package manager configs (dependency choices)

Package manager configs (dependency choices)

Firebase and cloud service configs

Firebase and cloud service configs

CI/CD pipelines

CI/CD pipelines

The three questions

三个关键问题