Front AI agent 환경 구축

스킬 파일의 단락은 최대 100 줄 까지만 작성 (그 이상으로 넘어가면 참고 파일로 ai agent가 바꿔서 읽어버림)
 
SKILL.md 에 포함되어야할 내용
  • 스킬 개요 및 사용자 시나리오
  • 퀵 레퍼런스
  • 브랜드 햄식 가치
  • 일반적인 사용 사례
references
  • colors.md
  • typography.md
  • communication.md
 
token 소모량은 input 보다 output token이 5배 더 비싸다.
 

Brain pattern

 
ROOT CLAUDE.md 파일에 각 폴더별 md 파일 규약 설명
 
레이어
기능 (Brain)
명칭
설명
p0
생존, 보안, 불변
p0-trust-first
변하지 않는 절대적인 규칙, 제약 사양
p1
자동화, 반복, 예약
p1-automation-rhythm
CI/CD, 코드 포맷팅, 반복적인 빌드/배포 스케줄
p2
기억, 상태 유지
p2-state-memory
전역 상태 관리 컨벤션, 캐싱 전략, 유저 세션 유지 → 데이터 흐름에 대한 설명을 명세
p3
위험 감지, 방어
p3-risk-detect
에러 핸들링, 테스트 가드레일, 런타임 예외 처리 → 버그나 보안 취약점 대응 레이어
p4
실행, 작업
p4-workflow
실제 UI 컴포넌트 개발, 비즈니스 로직 실행 순서
p5
자아, 스타일, 페르소나
p5-brand-identity
햄식 브랜드 가치, 톤앤매너, 디자인 토큰(Color/Typo)
p6
목표, 전략, 방향
p6-goal-strategy
현재 스프린트 목표, 프로젝트 로드맵, 가변적 비즈니스 우선순위 → 가장 자주 바뀌는 작업, 방향 즉, 에이전트가 자주 읽어야할 파폴더
 
 
숫자가 높을수록 가변, 낮을수록 불변 0번의 경우 불변의 룰을 정함
 

Root Level: 중추 신경계 (공통 규약)

프로젝트 최상위 루트에는 모든 앱과 패키지가 공유해야 하는 '절대 원칙'을 둡니다.
  • p0-trust-first: 모노레포 전체 보안, 의존성 관리 금기 사항.
  • p1-automation-rhythm: 전체 빌드(Turborepo/Nx 등), CI/CD 흐름.
  • p5-brand-identity: 브랜드 햄식 가치, 공통 디자인 토큰(Colors/Typo), 말투.
  • p6-goal-strategy: 모노레포 전체의 로드맵.
 

Apps/Packages Level: 말초 신경계 (개별 특화)

각 개별 프로젝트 안에는 해당 프로젝트에만 해당하는 '가변적인' 레이어만 둡니다.
  • p2-state-memory: (Apps 하위) 해당 앱의 특정 상태 트리, 데이터 흐름.
  • p4-workflow: (핵심) 해당 프로젝트의 구체적인 SKILL.md. (컴포넌트 작성법, 로직 구현법 등)
  • p6-goal-strategy: (Apps 하위) 이 특정 서비스가 이번 주에 해결해야 할 기능 단위 목표.
 
 

모노레포 구축 가이드라인

모든 곳에 생성하지 않는다.

에이전트가 특정 apps/project-a에서 작업할 때, Root의 P0, P5를 먼저 읽고, Local의 P4, P6를 결합해서 사고하도록 ROOT_CLAUDE.md에 명시.
"너는 작업을 시작할 때 루트의 p0, p5를 준수하며, 현재 작업 폴더의 p4, p6에 집중한다."
 

SKILL.md는 '작업 단위'로 분리

모노레포는 패키지가 많기 때문에, p4-workflow 내부의 SKILL.md가 100줄을 넘어갈 것 같으면, 기능을 쪼개야함
  • ui-kit/p4-workflow/SKILL-button.md
  • ui-kit/p4-workflow/SKILL-input.md 이렇게 하면 에이전트가 필요한 스킬 파일만 로드하므로 Input Token을 아낄 수 있다.
 

Output Token 5배 법칙 적용

패키지나 앱이 많을수록 에이전트가 전체 코드를 다 뱉으려고 할 위험이 큼 p5-brand-identity/communication.md에 다음과 같은 원칙을 박아두세요.
"모노레포 구조이므로, 코드 수정 시 전체 파일이 아닌 수정된 함수나 컴포넌트 단위(Partial code)로만 응답하여 전송 효율을 극대화한다."