对二十个功能共用的工具函数做了“小清理”
"Small cleanup" of a helper twenty features use
智能体在改某个功能时，顺着 import 进了共享工具文件并重构了它，所有调用方的行为都跟着变了。
适用于: Claude Code · Cursor · Codex · Copilot agent
症状
任务只涉及 `login.ts`，diff 却重写了 `utils/helpers.ts`。合并后，不相关的功能开始出问题。
为什么会这样
Night Forge 根据 Cursor 论坛的反馈，把“对共享工具的热心清理”列为反复出现的模式。智能体看到“水源地”文件里的旧写法就想改，却意识不到它的影响范围。
示例
摘自 Night Forge 的文章。
textAsked: change src/features/auth/login.ts
Agent: also refactored src/utils/helpers.ts (imported by ~20 features)
复制即用的修复
按你用的智能体挑选文件。规则片段用英文写，放进任何仓库都能用。
规则
Claude Code：加入 CLAUDE.md
CLAUDE.md## Shared code is off-limits by default
- Do not modify shared modules (`utils/`, `lib/`, `shared/`, `common/`, design-system components)
unless the task is about them.
- If the fix truly requires a shared change, stop, list the callers (`rg -l "from .*helpers"`), and ask.
- Prefer a local change in the feature over editing a shared helper.
规则
Codex、Copilot 编码智能体等：加入 AGENTS.md
AGENTS.md## Shared code is off-limits by default
- Do not modify shared modules (`utils/`, `lib/`, `shared/`, `common/`, design-system components)
unless the task is about them.
- If the fix truly requires a shared change, stop, list the callers (`rg -l "from .*helpers"`), and ask.
- Prefer a local change in the feature over editing a shared helper.
Cursor 规则
Cursor：项目规则
.cursor/rules/shared-helper-cleanup.mdc---
description: "AgentFails: 'Small cleanup' of a helper twenty features use"
alwaysApply: true
---
## Shared code is off-limits by default
- Do not modify shared modules (`utils/`, `lib/`, `shared/`, `common/`, design-system components)
unless the task is about them.
- If the fix truly requires a shared change, stop, list the callers (`rg -l "from .*helpers"`), and ask.
- Prefer a local change in the feature over editing a shared helper.
配置
共享代码需审批（CODEOWNERS）
.github/CODEOWNERS# Any PR (human or agent) touching shared code needs a maintainer's review
/src/utils/ @your-org/maintainers
/src/lib/ @your-org/maintainers
/src/shared/ @your-org/maintainers
钩子
Claude Code PreToolUse 钩子：拦截声明范围之外的编辑
改编自 dev.to（yureki_lab）的 diff budget 设计。在仓库根目录的 .agent-scope 中每行写一个允许的 glob。退出码 2 会阻止该工具调用，并把 stderr 反馈给智能体。它只覆盖文件编辑工具，shell 写入仍需靠 diff 检查兜底。
.claude/hooks/scope_guard.py#!/usr/bin/env python3
"""PreToolUse hook: block Edit/Write/MultiEdit outside the globs in .agent-scope."""
import fnmatch, json, os, sys
call = json.load(sys.stdin)
if call.get("tool_name") not in ("Edit", "Write", "MultiEdit"):
sys.exit(0)
root = os.environ.get("CLAUDE_PROJECT_DIR") or call.get("cwd") or os.getcwd()
scope_file = os.path.join(root, ".agent-scope")
if not os.path.exists(scope_file):
sys.exit(0) # no scope declared for this task -> allow
allowed = [l.strip() for l in open(scope_file) if l.strip() and not l.startswith("#")]
target = os.path.relpath(call["tool_input"]["file_path"], root)
if any(fnmatch.fnmatch(target, pat) for pat in allowed):
sys.exit(0)
print(
f"BLOCKED: {target} is outside this task's scope ({', '.join(allowed)}).\n"
"If this edit is required, stop and ask the user to widen .agent-scope, with a one-line reason.\n"
"If it is just an improvement you noticed, add it to FOLLOWUPS.md and keep going.",
file=sys.stderr,
)
sys.exit(2)