文件护栏

这个 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 - 超限后的拆分原则、流程与模式