# File Guardrails

> 文件级工程护栏能力单元，帮助 Agent 在新建、修改、重构代码文件时，同时控制顶部说明、单文件体量与拆分方式，确保文件易读、可维护、职责清晰，并在超过 300 行时立即停下并给出拆分方案。关键词：文件护栏、文件头注释、300 行限制、拆分方案、代码可读性、职责清晰。

- Skill: `qiao-925/file-guardrails` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add qiao-925/file-guardrails`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qiao-925/file-guardrails/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: qiao-925 (https://skillmd.com/u/qiao-925)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qiao-925/file-guardrails

---


# 文件护栏

> 这个 skill-unit 处理的是“单个代码文件如何保持可读、可控、可拆”问题。它把顶部说明与文件体量放在同一套护栏里管理。

## 核心原则

### 1. 顶部说明 —— 让首次读者先知道文件做什么

- 代码文件在适合注释的语法下，应提供简洁的顶部说明。
- 第一行说明文件用途，比罗列架构概念更重要。
- 顶部说明只解释文件意图、主要职责、必要时给最短使用示例。

### 2. 单文件上限 —— 300 行是硬约束

- 单个代码文件必须控制在 300 行以内。
- 这个限制不是建议，而是强约束。
- “功能复杂”“赶时间”“先这样”都不能成为超限理由。

### 3. 超限先停 —— 先给拆分方案，再继续写

- 一旦文件超过 300 行，应停止继续堆代码。
- 必须先给出拆分方案：拆成哪些文件、各自职责是什么、外部接口如何保持稳定。
- 拆分的目标不是转移混乱，而是收敛职责与阅读路径。

### 4. 注释克制 —— 解释意图，不复述代码

- 注释优先解释文件为什么存在、主要承担什么职责。
- 不写大段架构史、设计哲学和代码逐行翻译。
- 如果需要靠大段注释才能理解代码，优先考虑简化结构而不是继续补注释。

## AI Agent 行为要求

### 默认适用场景

| 场景 | 最低要求 | 不该做什么 |
|------|----------|------------|
| 新建代码文件 | 补最小顶部说明，并控制体量 | 上来写一大段注释模板 |
| 修改现有文件 | 检查注释是否过时，检查是否逼近上限 | 只加逻辑，不看文件是否已膨胀 |
| 重构大文件 | 先出拆分方案，再执行拆分 | 把一个大文件拆成很多职责仍混杂的小文件 |
| 代码审查 | 明确指出超限与头注释问题 | 只说“可以再优化”，不给具体护栏判断 |

### 默认执行方式

1. 新建或显著修改代码文件时，先判断该文件是否需要顶部说明。
2. 写完后检查文件行数；若接近上限，提前规划拆分。
3. 一旦超过 300 行，立即停下并输出拆分方案。
4. 更新顶部说明时，只保留首次阅读真正需要的信息。
5. 拆分后复核：文件更清晰了，而不是仅仅变多了。

### 顶部说明最小要求

- 一句话说明文件用途
- 必要时列出 2-4 个主要职责
- 对复杂文件，可补 2-4 个主要组成或阅读入口，帮助读者快速定位主路径
- 只有在边界容易被误判时，才用一句话说明“本文件不负责什么”
- 只有在上手成本较高时才补最短示例

### 不应强行添加顶部说明的情况

- 不支持注释语法的文件格式
- 纯数据文件、自动生成文件、第三方镜像文件
- 仓库内已有更强约定明确禁止此类头注释

### 场景化展开

- 涉及顶部说明写法时，读取 `references/header-comment-guidelines.md`
- 需要具体语言模板时，读取 `references/comment-templates.md`
- 涉及大文件拆分时，读取 `references/splitting-guide.md`

### 与其他 skill 的协同边界

- 与 `single-responsibility`：当文件超限的根因是职责混杂时联动，顺序为“先拆职责，再落文件边界”。
- 与 `core-first-simplicity`：当文件越来越大是因为顺手塞入非核心能力时联动。
- 与 `architecture-governance`：当拆分已上升到模块边界、层级依赖与公共接口设计时联动。

## 判断标准

- 首次阅读者能否在顶部快速理解文件用途。
- 对复杂文件，顶部说明是否帮助读者快速定位主要组成和职责边界。
- 文件是否仍能在短时间内读完主路径。
- 当文件接近或超过 300 行时，是否已经进入拆分讨论。
- 拆分后的文件是否职责更清晰，而不是仅做机械切块。
- 注释是否解释了意图，而不是重复代码表面信息。

## 反模式

- 用大段头注释掩盖糟糕结构。
- 文件已经超限，还继续往里加逻辑。
- 把大文件按行数平均切开，而不是按职责拆分。
- 在每个文件头部复制粘贴大段模板，制造噪音。
- 明明只是小改动，却让顶部说明和代码长期失真。

## 参考资料

- `references/header-comment-guidelines.md` - 顶部说明的写法与禁区
- `references/comment-templates.md` - Python、TS/JS、Shell、Go、Java 模板
- `references/splitting-guide.md` - 超限后的拆分原则、流程与模式