GEN AI Content

OpenAI Codex, Cursor, 그리고 다양한 에이전트 기반 코딩 도구(agentic coding tools)와 같은 AI 코딩 어시스턴트가 주류가 되면서, 개발자들은 공통적인 함정인 **문맥 손실 (Context Loss)**을 깨닫고 있습니다.

복잡한 애플리케이션을 구축할 때, AI 에이전트는 종종 전체적인 아키텍처 (architecture)를 잊어버리거나, 코딩 표준에서 벗어나거나, 실제 프로젝트를 진행시키지 못한 채 미시적인 수정 작업의 루프에 빠지곤 합니다. 해결책은 더 길고 복잡한 일회성 프롬프트를 작성하는 것이 아닙니다. 해결책은 **Markdown을 통한 상태 관리 (State Management via Markdown)**입니다.

이 기사에서는 여러분의 리포지토리(repository)에 두 가지 기초 파일인 AGENTS.md와 PLAN.md를 도입함으로써 AI 코딩 효율성을 획기적으로 높이는 방법을 보여드리겠습니다.

AI(Codex 또는 유사한 LLM 기반)에게 "사용자 인증 기능을 추가해줘"라고 요청할 때, AI는 몇 가지 장애물에 직면합니다:

• 사용자의 구체적인 아키텍처 (architectural) 선호도를 알지 못합니다.
• 무엇이 이미 구축되었고 무엇이 계획되어 있는지 알지 못합니다.
• 긴 채팅 세션 동안 희석되는 즉각적인 문맥 창 (context window)에만 전적으로 의존합니다.

이를 해결하기 위해, 우리는 AI를 매우 조직화된 팀에 합류하는 새로운 개발자로 취급합니다. 우리는 AI에게 **역할 (Role)**과 **로드맵 (Roadmap)**을 부여합니다.

PLAN.md는 프로젝트의 뇌의 기억 역할을 하는 살아있는 문서입니다. 새로운 채팅 세션을 열 때마다 프로젝트의 현재 위치를 설명하는 대신, 단순히 AI에게 다음과 같이 말하면 됩니다: "PLAN.md를 확인하여 현재 상태를 파악하고, 아직 체크되지 않은 다음 작업을 실행하세요."

상위 수준 아키텍처 (High-Level Architecture): 앱이 무엇을 하는지에 대한 간략한 요약.
현재 단계 (Current Phase): 프로젝트가 현재 어디에 와 있는지.
실행 가능한 체크리스트 (Actionable Checklists): 원자적이고 관리 가능한 단계로 세분화됨.

# 프로젝트 이름: TaskFlow API
**설명:** 경량 태스크 관리 REST API.
## 아키텍처 (Architecture)
...

Codex가 이 파일을 읽으면, 기술 스택 (tech stack), 무엇을 다시 만들 필요가 없는지(Phase 1이 완료되었으므로), 그리고 현재의 정확한 목표가 무엇인지를 즉시 이해합니다. 작업이 완료되면, AI에게 체크박스를 표시하여 PLAN.md 파일을 업데이트하도록 요청하세요.

PLAN.md가 '무엇(what)'을 할 것인가를 정의한다면, AGENTS.md는 '어떻게(how)' 할 것인가를 정의합니다.

서로 다른 작업에는 서로 다른 사고방식 (mindset)이 필요합니다. 어떤 날은 AI가 엄격한 보안 감사관 (Security Auditor) 역할을 수행하기를 원할 수도 있고, 다음 날은 창의적인 프론트엔드 디자이너 (Frontend Designer) 역할을 수행하기를 원할 수도 있습니다. AGENTS.md는 AI가 따라야 할 페르소나 (persona), 제약 조건 (constraints), 그리고 엄격한 코딩 규칙 (coding rules)을 정의합니다.

시스템 프롬프트 (System Prompts) / 페르소나 (Personas): 에이전트 역할에 대한 명확한 정의. -
엄격한 코딩 제약 조건 (Strict Coding Constraints): 타이핑 (typing), 테스트 (testing), 포맷팅 (formatting) 또는 금지된 라이브러리에 관한 규칙. -
커뮤니케이션 규칙 (Communication Rules): AI가 응답하는 방식 (예: "사과하지 말고 코드만 제공하세요").

# AI 에이전트 지침 (AI Agent Directives)
이 저장소와 상호작용할 때, 작업에 따라 다음 역할 중 하나를 채택해야 합니다. 지정되지 않은 경우, 기본값은 `@BackendDev`입니다.
## @BackendDev
...

이제 프로젝트 루트에 두 파일이 모두 준비되었으므로, Codex (또는 Cursor / Cline / GitHub Copilot과 같은 도구)를 사용하는 워크플로우가 믿을 수 없을 정도로 간소화됩니다.

새 세션을 시작할 때, 첫 번째 프롬프트는 다음과 같이 간단해야 합니다:

"현재 진행 상황을 이해하기 위해 PLAN.md를 읽고, 코딩 가이드라인을 이해하기 위해 AGENTS.md를 읽어주세요. @BackendDev 역할을 맡으세요. 2단계(Phase 2)에서 아직 완료되지 않은 다음 작업을 실행하세요."

AI는 파일을 읽고 JWT 토큰 생성 기능을 구축해야 함을 인지하며, AGENTS.md에 정의된 타입 힌팅 (type-hinting) 및 에러 핸들링 (error-handling) 규칙을 엄격히 준수하여 코드를 작성할 것입니다.

코드가 작성되고 테스트되면, 사이클의 마지막 명령을 내립니다:

"좋습니다. PLAN.md를 업데이트하여 JWT 작업을 완료 처리하고, 다음으로 /login 엔드포인트에 대한 기술적 접근 방식을 간략하게 개요를 작성해 주세요."

프로젝트 상태를 PLAN.md로, 시스템 프롬프트를 AGENTS.md로 외재화함으로써, 당신은 AI에게 프롬프트를 입력하는 단계에서 AI를 관리하는 단계로 전환하게 됩니다.

이 방법은 환각 (hallucinations)을 획기적으로 줄이고, 토큰 컨텍스트 (token context)를 절약하며 (AI가 프로젝트 구조를 추측할 필요가 없기 때문), 몇 주가 지난 후에도 흐름을 놓치지 않고 복잡한 프로젝트를 일시 중단했다가 다시 재개할 수 있게 해줍니다. 오늘 바로 당신의 리포지토리에 이 두 파일을 추가해 보세요. 그리고 당신의 AI 코딩 어시스턴트가 진정한 10x 엔지니어링 파트너로 변모하는 것을 확인하십시오!