file-header-guardian

Dimon94's avatarfrom Dimon94

文件头三行契约注释。触发:create file、新建文件、编写代码。

⭐95stars🔀25forks📁View on GitHub🕐Updated Jan 5, 2026⬇️2downloads

When & Why to Use This Skill

The File Header Guardian is a specialized Claude skill designed to automate and enforce standardized file header documentation. By implementing a 'three-line contract' (Input, Output, Position), it ensures that every code file maintains a clear architectural context. This skill streamlines developer workflows by automatically generating or validating header comments during file creation and modification, significantly improving codebase maintainability and team collaboration.

Use Cases

  • Automated Boilerplate Generation: Automatically inserts structured comment blocks (supporting TypeScript, JavaScript, Python, and Shell) whenever a new source file is created, ensuring immediate compliance with project documentation standards.
  • Codebase Maintenance and Refactoring: Validates and updates existing file headers during code modifications to ensure that 'Input' and 'Output' definitions remain accurate as the logic evolves.
  • Architectural Context Mapping: Uses the '@pos' (Position) tag to provide developers and AI agents with instant clarity on a file's specific role and hierarchy within the larger system architecture.
  • Documentation Synchronization: Facilitates the alignment between individual file-level metadata and global project maps (such as CLAUDE.md), preventing documentation rot in complex software projects.
namefile-header-guardian
description文件头三行契约注释。触发:create file、新建文件、编写代码。

文件头注释守护者

触发:创建代码文件,修改文件后检查头注释准确性。

模板

TS/JS:

/**
 * @input  依赖什么
 * @output 提供什么
 * @pos    系统地位
 * ⚠️ 修改后同步:文件头 + 目录 CLAUDE.md
 */

Python:

"""
@input  依赖什么
@output 提供什么
@pos    系统地位
⚠️ 修改后同步:文件头 + 目录 CLAUDE.md
"""

Shell:

# @input  依赖什么
# @output 提供什么
# @pos    系统地位
# ⚠️ 修改后同步:文件头 + 目录 CLAUDE.md

示例

/**
 * @input  prisma.service 数据库连接
 * @output UserService: create/update/delete
 * @pos    用户模块核心
 * ⚠️ 修改后同步:文件头 + 目录 CLAUDE.md
 */
export class UserService { }

豁免

配置文件(json/yaml)、样式(css)、生成文件(*.d.ts)、node_modules。

协作:本 skill 管文件,fractal-docs-generator 管目录。