AI 코딩 에이전트(coding agents)는 필요한 모든 것이 레포지토리에 존재할 때 가장 잘 작동하는데, 이는 코드 자체가 이들의 진실 공급원(source of truth)이기 때문입니다. 하지만 대부분의 팀은 여전히 Jira나 Redmine 같은 외부 도구에서 태스크와 요구사항을 추적합니다. 태스크를 단순한 Markdown 파일로 저장하면 상황이 달라집니다. 에이전트는 요구사항과 코드를 한 곳에서 읽을 수 있으며, 모든 태스크 변경 사항은 다른 커밋(commit)처럼 버전 관리되고 검토될 수 있습니다. Docs as Code 접근 방식은 이미 이러한 진화의 청사진을 제공하고 있으며, Git과 동기화되는 웹 인터페이스를 사용하면 기술 작가와 제품 오너들이 명령줄(command line)에 강제적으로 참여하지 않고도 상황을 파악할 수 있게 해줍니다.
Screenshot of tasks edited as Markdown in the IDE
Docs as Code
문서화는 이미 별도의 문서 소프트웨어에서 Git 레포지토리의 Markdown 파일로 전환되었습니다. 오늘날에는 종종 코드 레포지토리 내부의 /docs 폴더에 존재합니다. 이러한 관행은 Docs as Code 또는 Docs Like Code로 알려져 있습니다.
AI 코딩 에이전트와 함께 이 접근 방식은 더욱 유용해집니다. 에이전트는 문서를 읽어 시스템을 이해하고, 코드 변경을 수행하며, 동일한 워크플로우의 일부로 관련 문서를 업데이트할 수 있습니다. 따라서 문서화는 나중에 완료해야 하는 별도의 활동이라기보다는 소프트웨어 개발에 필수적인 부분이 됩니다.
Tasks as Code
이러한 원칙은 개발 태스크에도 적용됩니다. 태스크가 Markdown 파일로 저장되면, 에이전트는 이를 직접 읽고, 작업을 계획하는 데 사용하며, 결과를 동일한 파일에 기록할 수 있습니다. Git은 소프트웨어와 문서화의 이력과 함께 태스크 이력을 접근 가능하게 유지합니다.
이 아이디어는 이미 Spec-Driven Development (SDD)에서 반영되고 있습니다. SDD는 AI 에이전트가 구현하기 전에 Markdown을 사용하여 명세(specifications)를 정의하는 데 사용됩니다. 태스크 파일도 유사한 목적을 수행할 수 있지만, 상세 수준은 작업에 따라 다릅니다. 간단한 유지보수 태스크는 짧은 설명만 필요할 수 있는 반면, 복잡한 기능은 승인 기준(acceptance criteria), 기술적 결정 사항(technical decisions), 의존성(dependencies), 그리고 테스트 요구사항을 필요로 할 수 있습니다.
SDD는 종종 Spec Kit과 같은 전용 도구의 지원을 받지만, 시작하기에는 더 간단한 접근 방식만으로 충분합니다. 즉, 태스크 파일 자체를 명세(specification)로 취급하는 것입니다. 이렇게 하면 Git과 에이전트 외에 다른 것이 필요하지 않아 전환이 쉬워집니다.
다음은 5단계의 간단한 워크플로우입니다:
1. 태스크 설명 작성 (Describe the task). 구현해야 할 변경 사항이나 기능에 대한 짧은 설명을 작성합니다.
2. 요구사항 분석 (Analyze the requirements). 에이전트가 태스크를 읽고 관련 코드와 문서를 검토합니다.
3. 구현 계획 수립 (Create an implementation plan). 에이전트는 제안된 해결책을 추가하고 변경하려는 내용을 식별합니다.
4. 검토 및 승인 (Review and approve). 개발자가 계획을 검토하고 구현을 승인합니다.
5. 구현 및 보고 (Implement and report). 에이전트가 코드를 변경하고, 필요한 경우 문서를 업데이트하며, 태스크 파일에 구현 보고서를 첨부합니다.
태스크 설명, 구현 계획, 그리고 보고서는 하나의 파일에 함께 남아 있습니다. 이는 원래 요구사항을 검토하기 쉽고, 계획된 접근 방식을 이해하며, 에이전트가 실제로 무엇을 변경했는지 확인할 수 있게 해줍니다.
승인 단계는 사람의 통제권을 유지합니다. 에이전트는 태스크 설명에서 구현으로 바로 진행하지 않으며, 계획은 먼저 검토되고 수정될 수 있습니다.
예시 설정
제가 사용하는 환경에서는 세 개의 별도 Git 레포지토리(repository)를 사용합니다:
- Code (코드)
- Documentation (문서)
- Tasks (태스크)
문서와 태스크는 종종 다른 접근 권한 요구 사항을 가집니다. 문서는 공개적일 수 있지만, 태스크에는 미완성된 보안 수정, 내부 기획 또는 아직 발표되지 않은 기능에 대한 민감한 정보가 포함될 수 있습니다. 별도의 레포지토리를 사용하면 접근 권한을 독립적으로 구성하고 태스크를 비공개로 유지할 수 있습니다.
로컬 환경에서는 개발자가 문서 및 태스크 레포지토리를 코드 레포지토리 내부의 폴더로 클론(clone)합니다. 두 폴더 모두 코드 레포지토리의 .gitignore에 등록됩니다.
파일이 부모 레포지토리가 그 내용을 추적하지 않도록 합니다. 클론된 각 레포지토리(Repository)는 자체 Git 히스토리(Git history)를 유지하며 독립적으로 커밋(commit), 푸시(push), 동기화할 수 있습니다.
/code-repo
/src
/tests
...
모든 정보가 이제 Claude Code나 OpenCode와 같은 로컬 코딩 어시스턴트(local coding assistant)에서 사용할 수 있게 되었습니다. 에이전트(agent)가 작업을 구현할 때, 작업 내용을 읽고, 코드를 분석하며, 변경 사항을 구현하고, 관련 문서를 업데이트합니다. 구현 보고서는 해당 작업과 함께 유지되며, 실제 코드 변경 사항은 코드 레포지토리(code repository)에 기록됩니다. Git 커밋에서 작업 파일명을 참조하는 것은 구현을 원래 요구사항과 연결하는 데 도움이 됩니다.
작업들이 릴리스 폴더(release folders)로 구성될 때, 에이전트는 완료된 작업과 Git 히스토리를 사용하여 변경 로그(changelog)와 릴리스 노트(release notes)를 작성할 수 있습니다. 동일한 정보는 업데이트가 필요한 문서를 식별하는 데 도움을 줄 수 있습니다.
인터페이스 추가하기
이 워크플로우를 실행하려면 Git과 AI 코딩 에이전트만으로 충분합니다. 브라우저 기반의 인터페이스(browser-based interface)는 근본적인 버전 관리 시스템(version control system)으로서 Git을 대체하지 않으면서 파일을 탐색, 편집 및 구성하는 또 다른 방법을 추가합니다.
Typemill은 콘텐츠를 Git 레포지토리와 동기화할 수 있습니다. 여러 레포지토리를 지원하기 때문에, 문서 프로젝트와 별도로 개인 작업용 프로젝트를 설정할 수 있습니다. 이렇게 하면 내용이 분리된 레포지토리에 존재하더라도 동일한 인터페이스를 통해 둘 다 관리할 수 있습니다.
작업(Tasks):
Screenshot Tasks as Code
문서화(Documentation):
Screenshot of the documentation in Typemill
동일한 파일들은 세 가지 인터페이스를 통해 접근 가능합니다:
- IDE에서: 개발자와 AI 에이전트는 로컬 레포지토리와 직접 작업합니다.
- GitHub에서: 기여자(Contributors)는 레포지토리 인터페이스를 통해 변경 사항을 검토하고 파일을 편집할 수 있습니다.
- 브라우저에서: Typemill은 작업과 문서를 읽고 관리하기 위한 인터페이스를 제공합니다.
각 인터페이스는 서로 다른 목적을 수행합니다. IDE는 구현(implementation)을 지원하고, GitHub는 레포지토리 수준의 협업을 제공하며, CMS는 제품 오너(product owners)나 테크니컬 라이터(technical writers)와 같은 비기술적 사용자를 위한 콘텐츠 인터페이스 및 출판 플랫폼을 제공합니다. Git은 버전 기록과 동기화에 대한 책임이 남아 있습니다.
이러한 설정은 중요한 구분을 보여줍니다. 즉, 인터페이스가 데이터를 소유할 필요는 없다는 것입니다. 이는 파일들을 편리하게 다룰 수 있는 방법을 제공하며, 해당 파일들은 다른 도구들에도 여전히 이식 가능하고 접근성이 높습니다.
로컬(Local), 프라이빗(Private), 파일 기반(File-Based)
Typemill과 플랫파일 CMS는 이러한 워크플로우를 실험해 볼 수 있는 몇 가지 빠른 옵션일 뿐입니다. Markdown 파일을 Git에 보관하고 에이전트가 이에 접근할 수 있도록 하는 모든 설정이 작동할 것이며, 작업 파일 폴더만으로 시작할 수도 있습니다.
더 흥미로운 질문은 그다음 일입니다. 태스크(tasks)가 문서화와 함께 레포지토리로 들어오게 되면, 우리는 이 모델을 위해 설계된 새로운 소프트웨어와 인터페이스를 보게 될 것입니다. 개발자, 제품 오너, 테크니컬 라이터는 협업할 공유 공간이 필요하며, 에이전트 역시 그 워크플로우의 일부가 될 것입니다. 또한 현재 티켓 시스템에서 어떤 기능(예: 할당(assignments), 댓글(comments), 칸반 보드(kanban boards), 스프린트(sprints))이 여전히 필요한지에 대한 것도 미지수입니다. 만약 에이전트들이 대부분의 작업을 수행한다면, 아마도 이 모든 것이 아닐 것입니다.
위와 같은 설정을 바탕으로 제가 찾을 특성들은 다음과 같습니다:
Git 네이티브(Git-native): 태스크와 명세는 Git을 통해 관리되는 읽기 가능한 파일이며 코드 및 문서화와 연결되어야 합니다. 문서와 태스크의 통합: 하나의 인터페이스가 문서화와 태스크 관리에 모두 접근할 수 있도록 제공해야 합니다. 파일 기반: Markdown이 여전히 읽기 가능하고, 이식성이 높으며, 특정 플랫폼에 독립적이어야 합니다. 셀프 호스팅(Self-hosted): 팀들이 자신들의 데이터, 개인 정보 보호 및 인프라를 통제할 수 있어야 합니다. AI 서비스 개방성: 개발자들이 선호하는 AI 제공업체를 선택할 수 있도록 해야 하며, 인터페이스는 사용자를 단일 서비스에 가두기보다는 일반적인 통합(generic integrations)을 제공해야 합니다.
