GitHub 오픈소스 탐험

최근 AI 코딩 에이전트의 활용도가 높아짐에 따라, 이러한 에이전트들이 수행하는 작업의 관리와 계획이 점점 더 중요해지고 있습니다. 특히, 에이전트의 신뢰성과 지속성을 보장하는 것이 핵심 과제로 떠오르고 있습니다. 이번 블로그에서는 GitHub에서 주목받고 있는 오픈소스 프로젝트인 planning-with-files를 소개하겠습니다. 이 도구는 AI 코딩 에이전트와 장기 실행 작업을 위한 영구 파일 기반의 계획을 제공합니다. 이 글을 통해 이 도구가 어떤 문제를 해결하고, 어떻게 활용할 수 있는지를 알아보겠습니다.

프로젝트 개요

planning-with-files는 AI 코딩 에이전트가 수행하는 작업을 보다 효과적으로 관리하기 위해 설계된 도구입니다. 이 도구는 작업 계획을 저장하기 위한 markdown 파일(task_plan.md, findings.md, progress.md)을 사용하여, 에이전트가 컨텍스트 손실이나 작업 세션 초기화(/clear) 이후에도 계획을 지속적으로 유지할 수 있도록 도와줍니다. 특히, 이 도구는 다음과 같은 주요 기능을 제공합니다:

Persistent File-Based Planning: 작업 계획과 결과를 파일로 저장하여 언제든지 불러올 수 있습니다.
Session Recovery: 에이전트의 컨텍스트가 초기화되더라도 이전 세션의 계획을 복구할 수 있습니다.
Context Injection: 각 작업 턴마다 프로젝트 계획의 특정 컨텍스트를 자동으로 주입하여 작업의 연속성을 보장합니다.
Deterministic Completion Gate: 작업 완료 여부를 결정하는 문턱값을 설정할 수 있습니다.

이러한 기능들은 AI 코딩 에이전트가 보다 효과적으로 작업을 수행할 수 있도록 돕습니다.

설치 방법

이 도구는 npm, Claude Code 플러그인 마켓플레이스, 또는 npx를 통해 쉽게 설치할 수 있습니다. 다음은 설치 방법입니다:

npm을 통한 설치

npm install planning-with-files

npx를 통한 설치

npx planning-with-files

설치가 완료되면, 프로젝트에서 이 도구를 사용할 준비가 된 것입니다.

기본 사용법

이제 기본적인 사용법을 알아보겠습니다. 우선, 작업 계획을 작성하고, 이를 파일로 저장한 후, AI 코딩 에이전트와 통합하여 사용할 수 있습니다.

작업 계획 파일 생성

task_plan.md

# 작업 계획
## 목표
- 새로운 기능 개발
- 버그 수정

## 단계
1. 기능 요구사항 수집
2. 코드 작성
3. 테스트 및 배포

AI 코딩 에이전트와 통합

AI 코딩 에이전트에서 planning-with-files를 사용하여 작업 계획을 불러오고 진행 상황을 기록하는 방법은 다음과 같습니다.

# 작업 계획 불러오기
planning-with-files load task_plan.md

# 작업 진행
planning-with-files execute

이렇게 하면, 에이전트는 현재 작업 계획을 기반으로 작업을 수행하고, 그 결과를 findings.md와 progress.md에 기록하게 됩니다.

실무 활용 시나리오

이 도구는 다양한 실무 환경에서 활용될 수 있습니다. 예를 들어, 팀 프로젝트에서 여러 명의 개발자가 동시에 작업할 때, 각자의 작업 계획을 파일로 관리하고 이를 통해 진행 상황을 공유할 수 있습니다. 또한, 에이전트가 특정 작업을 수행하다가 중단되더라도, 이전 계획을 불러와서 계속 진행할 수 있어 작업의 연속성을 보장합니다.

비슷한 도구 비교

AI 코딩 에이전트와 함께 작업을 관리하는 도구는 여러 가지가 있지만, planning-with-files는 다음의 이유로 차별화됩니다:

파일 기반 저장: 데이터 손실 없이 영구적으로 작업 계획을 저장할 수 있습니다.
세션 복구 기능: 에이전트가 컨텍스트 손실 없이 이전 작업을 복구할 수 있습니다.
다양한 에이전트 지원: 60개 이상의 AI 에이전트와 호환되며, 다양한 플러그인을 제공합니다.

AI 코딩 에이전트의 업무를 돕는 파일 기반 계획 도구