文件护栏

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

核心原则

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

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

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

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

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