[#이론] 페이지 내 주석, 태그(키워드), 헬퍼(마이크로) 에이전트 등을 효율적으로 운용하기 위한 개인적인 아이디어와 AI의 답변. ⚖️

가장 추천하는 위치 패턴 (JS/TS)

A. 파일 최상단 (가장 중요 — 대표 명령어와 함께)

/**
* @fileoverview 사용자 프로필 관리 모듈
* @agent: profile-helper ← 여기서 주요 헬퍼 지정
* @secondary-agent: ui-helper
* @scope: entire file (lines 1-520)
*
* ==================== REPRESENTATIVE COMMANDS ====================

* 1. 모든 상태는 Zustand + immer로 관리
* 2. Accessibility (ARIA) 필수
* 3. 수정 후 lint + test 자동 실행
*
* @instruction: 위 명령을 기본으로 작업하고, @agent 태그에 따라 헬퍼가 주도하라.
*/

// ====================== HELPER BOUNDARIES ======================

B. 주요 섹션 / 모듈 시작 지점 (가장 자주 사용)

// ====================== AUTH HELPER BOUNDARY ======================
// @agent: auth-helper
// @scope: lines 80-220 only
// @rules:
// - JWT 관련 로직만 수정
// - rate limiting 반드시 적용
// - console.log 절대 남기지 말 것
async function loginUser(credentials) {
// ...
}

// ====================== PROFILE HELPER BOUNDARY ======================
// @agent: profile-helper
export const useProfileStore = create((set) => ({
// ...
}));

C. 개별 함수/컴포넌트 바로 위

/**
* 프로필 업데이트 처리
* @agent: profile-helper
* @command: optimistic update + error rollback 구현
* @priority: high
*/
export async function updateProfile(data) {
// ...
}

D. 파일 내 여러 헬퍼를 구분할 때 (경계선 스타일)

// ==================== [auth-helper 영역 시작] ====================
// @agent: auth-helper
// @end: line 180

// ... auth 관련 코드 ...

// ==================== [auth-helper 영역 종료] ====================
// ==================== [ui-helper 영역 시작] ====================
// @agent: ui-helper
// @scope: 200-450

2. 실전에서 가장 많이 쓰이는 태그 모음

@agent: 헬퍼이름 → 주요 담당 헬퍼
@secondary-agent: 이름 → 보조 헬퍼
@scope: lines xxx-yyy 또는 this function only 또는 entire file
@rules: 또는 @constraints:
@command: → 이번에 해야 할 구체적 작업
@instruction: → 에이전트에게 주는 지시문
@priority: high/medium/low

3. LangGraph Supervisor에게 잘 읽히는 전체 예시

// @file-agent: profile-helper
// @supervisor-instruction:
// 이 파일을 열거든 반드시 상단 REPRESENTATIVE COMMANDS를 먼저 읽고,
// 해당 @agent 헬퍼를 깨워 작업을 맡겨라.

export const ProfilePage = () => {
// ...
};

추천하는 위치 순서 (효과성 기준)

파일 최상단 (대표 헬퍼 + 대표 명령어)

각 주요 섹션 시작

(// ====================== HELPER BOUNDARY)

중요 함수/컴포넌트 바로 위 (JSDoc 안에 @agent)

필요 시 섹션 끝에 종료 표시

이렇게 하면 메인 Supervisor가 “profile 모듈 열어”라고 했을 때, 파일 상단을 보고 바로 profile-helper를 깨워서 작업을 시킬 수 있어요.