mdflow: Markdown 형태로 프롬프트를 작성한 뒤, CLI 명령어처럼 실행할 수 있도록 하는 프로젝트

9bow · 12월 13, 2025, 6:30오전

mdflow 소개

mdflow는 개발자가 작성한 마크다운(Markdown) 파일을 '실행 가능한 AI 에이전트'로 변환해주는 CLI(Command Line Interface) 도구입니다. Script Kit의 제작자로 유명한 John Lindquist가 개발한 이 프로젝트는 "당신의 마크다운 파일이 이제 실행 가능한 AI 에이전트가 됩니다(Your markdown files are now executable AI agents)"라는 핵심 아이디어를 바탕으로 합니다.

기존의 AI 상호작용이 주로 웹 기반의 채팅 인터페이스에서 이루어졌다면, mdflow는 이를 코드 중심의 워크플로우로 가져옵니다. 개발자는 마크다운 파일에 프롬프트를 작성하고, 파일 확장자나 이름을 통해 실행할 AI 모델(Claude, Gemini, OpenAI Codex 등)을 지정할 수 있습니다. 이는 프롬프트를 코드로 관리하고, 버전을 제어하며, 기존의 유닉스(Unix) 파이프라인과 결합하여 자동화된 작업을 수행할 수 있게 해줍니다.

mdflow 도구는 반복적인 AI 작업을 스크립트화하거나, 복잡한 프롬프트 엔지니어링을 파일 단위로 구조화하여 관리하고 싶은 개발자들에게 특히 유용합니다. 또한, 로컬 파일을 읽어 AI에게 전달하거나, AI의 출력을 다른 명령어의 입력으로 연결하는 등 터미널 환경에서의 유연한 AI 활용을 지원합니다.

Web UI 기반의 ChatGPT 및 Claude 등의 서비스가 대화형(Conversation) 중심이라면, mdflow는 스크립트 실행(Execution) 중심입니다. 즉, 사용자가 실행하는 프롬프트 내용이 파일로 저장되므로 재사용과 수정이 용이합니다. 또한, Web UI 기반 서비스에서는 웹 브라우저에 파일 업로드나 텍스트 복사/붙여넣기 등을 의존해야 하지만, mdflow는 표준 입출력(stdin/stdout)을 지원합니다. 즉, cat file.txt | mdflow task.md와 같이 리눅스 명령어와 결합하여 데이터를 유연하게 처리할 수 있습니다.

mdflow의 주요 기능

mdflow의 핵심은 마크다운 파일 자체가 하나의 실행 명령어가 된다는 점입니다. 파일명, Frontmatter, 본문(Body)이 각각 명령어, 옵션, 인자로 매핑됩니다.

파일명 기반 명령어 추론 (Filename Inference)

마크다운 파일의 이름에 포함된 키워드를 통해 실행할 AI 모델을 자동으로 결정합니다. 별도의 설정 없이 파일 생성만으로 즉시 실행이 가능합니다. 예를 들어, 다음과 같이 동작합니다:

task.claude.md → Claude 모델로 실행
task.gemini.md → Gemini 모델로 실행
task.codex.md → OpenAI Codex 실행
task.copilot.md → GitHub Copilot CLI 실행

Frontmatter를 통한 CLI 플래그 설정

마크다운 상단의 YAML Frontmatter 영역에 정의된 키(key)들은 자동으로 CLI 플래그로 변환되어 실행 시 전달됩니다. 복잡한 매핑 없이 직관적으로 옵션을 제어할 수 있습니다. 특히, 모델의 종류(model) 뿐만 아니라 온도(temperature), 시스템 프롬프트 등을 코드로서 명시하고 저장할 수 있습니다. 아래 예시를 참고해주세요:

---
model: opus                      # --model opus 로 변환
dangerously-skip-permissions: true # 권한 확인 건너뛰기
mcp-config: ./mcp.json           # MCP 설정 파일 지정
---
이곳에 작성된 내용은 프롬프트로 전달됩니다.

유닉스 철학 준수 (Unix Philosophy)

mdflow는 "작은 도구가 한 가지 일을 잘하게 하고, 서로 연결되게 한다"는 유닉스 철학을 따릅니다. 이를 위해 mdflow는 표준 입/출력(STDIN/STDOUT)을 지원하며, 사용자는 파이프(|)를 통해 데이터를 입력받거나, 실행 결과를 다른 도구로 전달할 수 있습니다. 이러한 기능을 활용하여 여러 에이전트 파일을 체이닝(Chaining)하여 복잡한 작업을 단계별로 처리할 수 있습니다.

템플릿 변수 및 상호작용

mdflow는 정적인 마크다운 파일을 사용자 입력을 받는 동적인 CLI 프로그램으로 활용할 수 있도록 템플릿 변수 및 상호작용 기능을 지원합니다. 개발자는 이 기능을 활용하여 매번 프롬프트 파일을 변경할 필요 없이, 하나의 파일을 다양한 목적에 재사용할 수 있습니다.

템플릿 변수는 이중 중괄호 {{ _변수명 }}로 감싸서 표현합니다. 변수 이름 앞에는 언더스코어(_)를 추가하여 {{ _varname }}과 같은 방식으로 사용할 수 있습니다.

---
model: sonnet
---
새로운 기능 "{{ _feature_name }}"에 대한 코드를 작성해주세요.

이렇게 선언한 변수 값은 CLI 명령 실행 시 플래그나 frontmatter 등, 여러가지 방법으로 결정됩니다. mdflow는 다음과 같은 순서로 마크다운 파일 내부의 변수 값을 결정합니다:

CLI 플래그: 터미널 명령어에서 직접 전달된 값을 가장 우선적으로 사용합니다. --key value 방식으로 실행합니다.
Frontmatter: CLI 플래그가 주어지지 않은 경우, 파일 상단에 미리 정의된 값을 사용합니다.
대화형 프롬프트: 위 두 곳에서 값이 주어지지 않은 경우, mdflow는 사용자에게 어떠한 값을 가져야 하는지 물어봅니다.

그 외, mdflow 엔진이 내부적으로 채워주는 시스템 변수(System Keys)나 {{ _1 }}, {{ _2 }} 등과 같이 자동으로 주입된느 템플릿 변수 또한 존재합니다. 자세한 내용은 mdflow 저장소의 README 문서를 참고해주세요.

출력(Print) 및 상호작용(Interactive) 모드 지원

기본적으로 mdflow는 출력(Print) 방식으로 실행됩니다. 출력 모드에서는 mdflow 실행 후 AI의 응답을 표준 출력(stdout)으로 내보내고 즉시 종료됩니다. 이 방식은 다른 리눅스 명령어들과 파이프(|)로 연결하거나, 결과를 파일로 저장할 때 사용됩니다. 즉, 다음과 같은 방식으로 처리합니다: 입력(Prompt) \rightarrow AI 처리 \rightarrow 출력(Stdout) \rightarrow 프로세스 종료

이러한 출력 모드는 실행 결과가 순수한 텍스트이므로, 이를 바로 다른 도구의 입력으로 넘길 수 있습니다. 따라서 셸 스크립트(Shell Script)나 CI/CD 파이프라인 내부에서 사용하는 등, 자동화에 사용하기 편합니다. 예를 들어 macOS에서 AI가 작성한 커밋 메시지를 바로 클립보드에 복사하려면 mdflow commit-msg.md | pbcopy과 같은 방식으로 실행할 수 있습니다.

mdflow는 챗봇(Chatbot) 경험을 터미널로 가져온 상호작용(Interactive) 방식도 함께 지원합니다. 이러한 방식은 사용자가 AI의 결과물을 보고 추가적인 수정 요구나 질문을 해야 할 때 유용합니다. 프로세스가 종료되지 않고 사용자의 입력을 대기하며, 이전 대화 맥락(Context)을 유지합니다: 입력 \rightarrow AI 처리 \rightarrow 출력 \rightarrow 사용자 입력 대기 \rightarrow (반복)

이러한 상호작용 모드는 사용자가 AI와 대화를 주고받으며 결과물을 다듬을 수 있어, 생성된 코드가 마음에 들지 않거나 버그가 있을 때, "이 부분 수정해줘" 등과 같은 방식으로 활용할 수 있습니다. 상호작용 모드로 실행을 하기 위해서는 mdflow 실행 시 --chat 플래그를 붙여 실행하거나, 설정에 따라 활성화할 수 있습니다. 예를 들어, 코드 리뷰를 진행하며 궁금한 점을 계속 질문하기 위해 상호작용 모드로 실행하는 경우 mdflow code-review.md --chat와 같이 실행하면 됩니다.

기타 고급 기능

mdflow는 이외에도 몇 가지 고급 기능들을 제공합니다:

먼저 스마트 캐싱 (Smart Caching) 입니다. 프롬프트에 포함된 외부 URL의 콘텐츠를 가져올 때, 이를 자동으로 로컬 디렉토리(~/.mdflow/cache/)에 저장하여 관리합니다. 기본적으로 1시간(TTL) 동안 캐시가 유지되므로, 짧은 시간 내에 동일한 리소스를 다시 참조할 경우 불필요한 네트워크 요청을 방지하고 즉각적으로 응답합니다. 이는 반복적인 디버깅이나 테스트 실행 시 발생할 수 있는 API 호출 비용을 절약하고, 작업 대기 시간을 획기적으로 단축시키는 데 매우 효과적입니다.

또한, MCP (Model Context Protocol) 통합 또한 지원합니다. Anthropic이 제안한 개방형 표준인 MCP를 지원하여, AI 모델이 단순한 텍스트 생성을 넘어 로컬 데이터베이스나 파일 시스템과 직접 상호작용할 수 있게 합니다. Frontmatter에 설정 파일(mcp-config) 경로를 지정함으로써, AI를 실제 데이터를 조회하거나 시스템을 제어할 수 있는 능동적인 에이전트로 확장할 수 있습니다. 이를 활용하면 로컬 DB 스키마를 읽어 최적화된 SQL 쿼리를 작성하거나, Git 저장소의 변경 사항을 분석하는 등 복잡하고 실질적인 워크플로우 구현이 가능합니다.

그 외에도 숙련된 사용자를 위한 YOLO 모드 (YOLO Mode) 도 지원합니다. YOLO 모드는 AI가 제안한 셸 명령어 실행이나 파일 수정에 대해 사용자에게 묻는 모든 확인(Confirmation) 절차를 건너뛰고 즉시 작업을 수행합니다. Frontmatter에 yolo: true를 설정하면 안전 확인으로 인한 중단 없이 매우 빠른 속도로 자동화 작업을 처리할 수 있습니다. 다만, 시스템에 직접적이고 되돌릴 수 없는 변경을 가할 수 있으므로, 검증된 프롬프트나 안전한 샌드박스 환경에서만 주의 깊게 사용해야 합니다.

그 외에도 Frontmatter 영역에서 단순히 모델을 선택하는 것을 넘어, temperature(창의성 및 무작위성 조절)나 system(시스템 프롬프트) 같은 핵심 파라미터를 세밀하게 제어하는 등, 모델 파라미터 미세 조정도 가능합니다. 이를 통해 "보안을 최우선으로 하는 시니어 백엔드 개발자"와 같은 구체적인 페르소나를 부여하거나, 코드 생성의 정확도를 높이기 위해 창의성 수치를 낮추는 등 목적에 최적화된 설정을 파일에 저장할 수 있습니다. 이 기능은 일회성 답변을 넘어, AI의 답변 스타일과 행동 원칙을 프로젝트 성격에 맞춰 일관되게 유지하는 데 필수적입니다.

mdflow 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~