헤더 기반 AI 컨텍스트 관리: 5줄 핵심 정리

핵심 원리: AI가 무조건 읽는 소스 코드 헤더에 핵심 정보를 집중시켜, 별도 문서 없이도 파일의 역할·의존성·변경 이력을 한눈에 파악하게 한다.

📋 표준 헤더 템플릿 (5줄)

/**
 * [AI_MODE] 파일명 - 역할 - v버전 (날짜)
 * [목적] 이 파일이 존재하는 이유 (한 줄)
 * [핵심] 주요 함수/흐름 (3~5개 키워드)
 * [연관] 의존 파일/API/테이블 (쉼표 구분)
 * [변경] 최근 수정 이력 (날짜-내용)
 */
💡 적용 효과
효과  설명
강제 컨텍스트 AI가 파일을 읽으면 헤더를 무조건 보게 됨
자기 동기화  코드 수정 시 함께 갱신되어 문서-코드 불일치 해소
인수인계 용이 파일만 봐도 역할/의존성/이력을 바로 파악
🔧 실천 규칙
신규 파일: 헤더 템플릿을 붙여넣고 시작

파일 수정: 헤더의 [변경] 항목에 변경사항 추가

AI 요청: 작업 전 헤더를 먼저 읽도록 지시

📌 실제 적용 예시
PHP 파일
php
<?php
/**
 * [AI_MODE] api/order.php - 주문 처리 API - v2.1 (2026-07-08)
 * [목적] POS/ERP 주문 생성·수정·취소 처리
 * [핵심] createOrder() / updateOrder() / cancelOrder() / validateStock()
 * [연관] api/inventory.php, db/order.sql, /payment/gateway.php
 * [변경] 2026-07-08: 재고 차감 로직 개선 / 2026-07-05: 취소 API 추가
 */
Python 파일
python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
[AI_MODE] cs4_markdown_generator.py - MD 생성기 - v1.0 (2026-07-08)
[목적] 크롤링 데이터 → Gemini API → 마크다운 일괄 생성
[핵심] load_json() / generate_markdown() / save_md() / validate_quality()
[연관] cs3_crawler.py, cs5_quality_check.py, /data/raw/
[변경] 2026-07-08: 최초 작성 / 2026-07-05: 체크포인트 시스템 추가
"""
🎯 이 방식이 효과적인 이유
text
AI가 파일을 읽을 때의 시선 흐름:
┌─────────────────────────────────────────────────────────────┐
│ 1. 파일 상단 (헤더) → 무조건 읽음                          │
│ 2. 클래스/함수 선언부 → 구조 파악                          │
│ 3. 핵심 로직 → 실제 작업 수행                              │
└─────────────────────────────────────────────────────────────┘

→ 따라서 헤더에 핵심 정보를 넣으면 AI는 "무조건" 그 정보를 알게 됨
💬 AI와의 협업 시 활용법
AI에게 작업을 요청할 때 이렇게 말해보세요:

"api/order.php 파일을 수정하려고 해. 헤더의 [목적]과 [핵심]을 먼저 읽고, [연관]된 파일들의 영향을 고려해줘. 수정 후에는 헤더의 [변경]에 변경사항을 기록해줘."

🔄 전체 문서와의 관계
정보 유형   저장 위치   이유
파일별 핵심 정보   소스 헤더   AI가 무조건 보게 됨
공통 규칙/철학    CLAUDE.md   프로젝트 전체의 일관성 유지
시스템 아키텍처    system.md   큰 그림을 문서로 보관
변경 이력   CHANGELOG.md    시간순으로 정리
🎯 한 줄 요약: "MD 문서는 선택적 컨텍스트, 소스 헤더는 강제적 컨텍스트. 중요한 정보는 AI가 무조건 보는 헤더에 넣어라."

이 5줄 템플릿이면 AI가 헤매지 않고, 문서와 코드가 불일치하지 않으며, 누구나 쉽게 인수인계받을 수 있습니다.