qiao-925 文件护栏
这个 skill-unit 处理的是“单个代码文件如何保持可读、可控、可拆”问题。它把顶部说明与文件体量放在同一套护栏里管理。
核心原则
1. 顶部说明 —— 让首次读者先知道文件做什么
- 代码文件在适合注释的语法下，应提供简洁的顶部说明。
- 第一行说明文件用途，比罗列架构概念更重要。
- 顶部说明只解释文件意图、主要职责、必要时给最短使用示例。
2. 单文件上限 —— 300 行是硬约束
- 单个代码文件必须控制在 300 行以内。
- 这个限制不是建议，而是强约束。
- “功能复杂”“赶时间”“先这样”都不能成为超限理由。
3. 超限先停 —— 先给拆分方案，再继续写
- 一旦文件超过 300 行，应停止继续堆代码。
- 必须先给出拆分方案：拆成哪些文件、各自职责是什么、外部接口如何保持稳定。
- 拆分的目标不是转移混乱，而是收敛职责与阅读路径。
4. 注释克制 —— 解释意图，不复述代码
- 注释优先解释文件为什么存在、主要承担什么职责。
- 不写大段架构史、设计哲学和代码逐行翻译。
- 如果需要靠大段注释才能理解代码，优先考虑简化结构而不是继续补注释。
AI Agent 行为要求
默认适用场景
| 场景 | 最低要求 | 不该做什么 |
|---|---|---|
| 新建代码文件 | 补最小顶部说明，并控制体量 | 上来写一大段注释模板 |
| 修改现有文件 | 检查注释是否过时，检查是否逼近上限 | 只加逻辑，不看文件是否已膨胀 |
| 重构大文件 | 先出拆分方案，再执行拆分 | 把一个大文件拆成很多职责仍混杂的小文件 |
| 代码审查 | 明确指出超限与头注释问题 | 只说“可以再优化”，不给具体护栏判断 |
默认执行方式
- 新建或显著修改代码文件时，先判断该文件是否需要顶部说明。
- 写完后检查文件行数；若接近上限，提前规划拆分。
- 一旦超过 300 行，立即停下并输出拆分方案。
- 更新顶部说明时，只保留首次阅读真正需要的信息。
- 拆分后复核：文件更清晰了，而不是仅仅变多了。
顶部说明最小要求
- 一句话说明文件用途
- 必要时列出 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- 超限后的拆分原则、流程与模式