코딩 에이전트의 행동을 설계하는 마크다운 메타코드
소프트웨어 개발 지식이 기존의 위키나 티켓 시스템에서 코딩 에이전트가 쉽게 읽고 활용할 수 있는 마크다운 기반 파일 형태로 코드베이스 옆에 저장되기 시작했습니다. 이러한 파일 묶음을 메타코드 레이어라 부르며, 개발자의 의도와 판단을 에이전트가 이해할 수 있는 규격 형태로 전달합니다.
주요 마크다운 파일 구조
- 온보딩 및 상시 규칙
- AGENTS.md : 프로젝트 구조, 빌드/테스트 명령, 코딩 컨벤션, PR 규칙 등을 담은 중립적 안내서.
- 기타 규칙 파일 : CLAUDE.md, .claude/rules/, GEMINI.md, GitHub Copilot 지침 파일 등 프레임워크/벤더별 규칙 파일 포함.
- 반복 가능한 절차 패키징
- SKILL.md : 특정 작업(예: DB 마이그레이션) 수행에 필요한 가이드, 스크립트, 템플릿, 참고자료 등을 패키지 형태로 제공하는 구체적인 워크플로우 정의.
- 변경 의도 문서화 : 에이전트 구현 전 사람이 검토할 수 있도록 명세 및 계획을 체계화.spec.md (요구사항 및 목적) $\rightarrow$ plan.md (기술 설계 및 접근 방식) $\rightarrow$ tasks.md (실행 단위 분할) 단계로 이어진 워크플로우 적용.
- 도메인 특화 맥락
- ARCHITECTURE.md (시스템 경계, NFR, 결정 사항), DESIGN.md (디자인 시스템), AUTH.md (인증 로직), REVIEW.md (코드 리뷰 우선순위) 등 특정 영역의 엔지니어링 지식 기재.
- 내구성 있는 학습 내역
- MEMORY.md : 빌드 전제 조건이나 디버깅 패턴 등 에이전트가 작업 중 배운 유용한 비정형 학습 내역 보관. 로컬 기록 후 검토를 거쳐 프로젝트 공통 규칙이나 아키텍처 문서로 승격.
결론
- 코딩 에이전트는 사람이 작성한 메타코드를 실제 실행 가능한 소스 코드로 변환해 주는 의도 컴파일러 역할을 하게 되며, 지식 파일들을 최신 상태로 스코프에 맞게 관리하는 것이 핵심 엔지니어링 과제로 부상하고 있습니다.
