도입: AI에게 「생각하고 실행하게」 하기 위해 부족한 것

ChatGPT나 Claude 등의 AI 도구를 업무에 도입했지만, 「채팅 대화가 산만해진다」, 「매번 같은 전제를 설명하는 것이 번거롭다」, 「며칠이 지나면 AI가 문맥을 잊어버린다」와 같은 벽에 부딪히고 계시지 않습니까?

AI를 단순한 「채팅 상대」나 「부분적인 자동화 도구」에서 「자율적으로 프로젝트를 진행하는 파트너」로 끌어올리기 위해서는, **AI와 인간 양측이 읽고 쓸 수 있는 「공통의 기억 영역 (상태 관리, State Management)」**이 필요합니다.

이 기사에서는 GitHub와 Markdown의 조합을 통해, AI 에이전트에게 프로젝트의 상태를 올바르게 인식시키고, 다음에 수행해야 할 태스크를 자율적으로 판단·실행하게 하기 위한 실천적인 아키텍처를 해설합니다.

과제: 채팅 UI의 한계

통상적인 채팅 UI로 AI와 일할 경우, 다음과 같은 문제가 발생합니다.

기억의 휘발과 컨텍스트 윈도우 (Context Window)의 한계: 긴 대화 속에서 초기 제약 사항이나 결정 사항이 잊혀진다. -
채택·기각 안의 혼재: 브레인스토밍 단계의 아이디어와 최종 결정된 사실이 동일한 타임라인상에 섞여 AI가 혼란을 겪는다. -
인간의 수작업 의존: AI가 생성한 텍스트를 인간이 복사하여 파일을 업데이트하는 수고가 남는다.

이러한 문제를 해결하려면 「채팅 이력」에 의존하는 것이 아니라, 「확정된 현재 상태」를 파일로서 유지하는 메커니즘이 필요합니다.

해결책: Markdown을 통한 상태의 객체화

AI에게 프로젝트의 상태를 인식시키기 위해, 리포지토리 내에 역할별 Markdown 파일을 배치합니다.

AGENTS.md / START.md

1. 공통 규칙 정의 (AI가 작업을 시작할 때 반드시 가장 먼저 읽어야 할 「헌법」을 정합니다.)

• 정본(正本)은 무엇인가 (예: 「main 브랜치의 Markdown 파일을 정본으로 한다」) -
• 금지 사항 (예: 「개인정보나 기밀 정보는 커밋하지 않는다」, 「임의로 판단을 덮어쓰지 않는다」) -
• 워크플로우 (Workflow) (예: 「작업 전에 현황을 읽고, 완료 시에 로그를 남긴다」)

00_CURRENT_STATE.md

2. 현재 위치 공유 (프로젝트의 「지금」을 기술합니다.)

• 목적과 최종 목표
• 현재 달성하고 있는 것
• 현재의 과제나 질문

04_NEXT_ACTIONS.md

3. 다음 액션 정의 (인간 또는 AI가 다음에 수행해야 할 「단 하나의 구체적인 작업」을 명확히 합니다. 이를 통해 AI가 「다음에는 무엇을 하면 될까요?」라고 인간에게 물으며 멈추는 것을 방지합니다.)

thinking_logs/ / EXPERIMENT_LOG.md

4. 사고와 검증의 기록 ("왜 그 변경을 했는가", "어떤 가설로 움직였는가"를 남깁니다. AI는 과거의 판단 로그를 읽음으로써 동일한 실수를 반복하지 않고, 컨텍스트에 부합하는 정밀도 높은 코드나 텍스트를 생성할 수 있게 됩니다.)

실천: AI와의 협업 워크플로우

이 체제를 구축하면 인간과 AI의 작업은 다음과 같이 분리·비동기화됩니다.

• 인간의 역할: 최종적인 방향성 결정, 외부 환경 (예: 고객 대응, 운영 환경의 인증) 대응, 그리고 AI가 생성한 Pull Request의 리뷰 및 머지 (Merge).
• AI의 역할: START.md와 현재 위치를 읽어 들여, 스스로 플랜을 세우고, 코드나 문서를 다시 쓰고, 검증 로그를 업데이트하며, Pull Request를 작성한다.

Zenn × GitHub 연계의 강점 (응용 사례)

이 메커니즘은 문서나 시스템 구축뿐만 아니라, 콘텐츠 판매와도 직결됩니다.

예를 들어 이 Zenn 기사 자체도, AI가 과거의 검증 로그를 읽고 과제(AI 운용에 고민하는 계층)를 추출하여, 자동으로 Markdown 파일을 생성·커밋함으로써 집필되었습니다.

인간이 Zenn과 GitHub 리포지토리를 연계(배포 설정)해 두면, AI가 기사를 쓰고 푸시(Push)하는 것만으로, 인간이 Zenn 관리 화면을 열지 않고도 유료 기사로서 자동으로 출판되는 워크플로우가 완성됩니다.

요약

AI의 성능은 급격히 향상되고 있지만, 그것을 최대한으로 끌어내는 것은 **「환경의 설계」**입니다.

GitHub와 Markdown을 통한 상태 관리를 도입함으로써, 인간의 「지시·복사·관리」 수고를 최소화하고, AI가 자율적인 가치 창조를 수행하도록 만드는 것이 가능해집니다.

우선은 당신의 프로젝트 디렉토리에 AGENTS.md

및 CURRENT_STATE.md를 생성하여, AI에게 "현재 상황"을 알려주는 것부터 시작해 보세요.

Discussion