ONEDEV

mdflow

AI Coding ToolsskillTypeScript

★ 604조회 4

무엇인가

mdflow는 반복되는 에이전트 작업을 저장소 안의 마크다운 파일로 정의하고, 그 정의를 CLI로 실행·검사·평가하도록 규율한다. 규율 대상은 작업 정의 자체, 엔진 선택, 컨텍스트 격리, 행동 평가, 프롬프트 개정 승인 절차다. 프롬프트를 채팅 세션과 개인 설정에 흩어 두지 않고 버전 관리 대상 파일로 옮긴다.

어떻게 동작하나

파일 구조는 `./flows` 디렉터리에 작업당 `.md` 하나를 두는 방식이다. frontmatter의 `engine:`, `_system-prompt:`, `_append-system-prompt:`, `_task:`, `_isolated:` 키가 실행 조건을 지정한다. 엔진 해석 순서는 `--engine` 플래그 > `MDFLOW_ENGINE` 환경변수 > 파일명 접미사(`review.claude.md`) > frontmatter `engine:` > config `engine:` > 내장 기본값(pi)이며, 암시적 선택은 `review.md → pi (engine: default)` 같은 흐림 줄로 출력된다. frontmatter도 명시 엔진도 없는 파일은 문서로 취급되어 `md README.md`는 실행 대신 내용을 출력한다. `md roster sync --agents`는 `AGENTS.md`와 `CLAUDE.md` 안에 마커로 감싼 mdflow 블록 하나를 유지해 코딩 에이전트가 로스터를 발견하고 맞는 작업을 플로우로 넘기게 하며, 마커 밖 텍스트는 수정하지 않는다.

무엇과 다른가

프롬프트를 직접 쓰거나 단일 규칙 파일에 몰아넣는 방식과 달리, 작업당 파일 하나를 두어 PR에서 diff하고 `md eval`로 선언된 행동을 검증한다. 엔진은 파일명 의식이 아니라 환경으로 취급되어 같은 플로우를 여러 엔진에서 돌릴 수 있다. 컨텍스트 격리가 기본값이라 엔진의 앰비언트 스킬·MCP·컨텍스트를 자체 플래그로 제거하고, 필요한 것은 frontmatter에 명시적으로 선언한다. 개정은 proposal-first로 진행되어 `md feedback`이 증거를 기록하고, `md evolve plan`이 증명·능력·쓰기·호출 비용을 무료로 미리 보여주며, `md evolve propose`가 오프패스 스냅샷을 초안·평가하고, 별도 `md evolve apply` 전까지 원본은 바이트 단위로 동일하게 유지된다.

어떻게 쓰나

설치는 `npx mdflow init`으로 `./flows` 로스터와 `.mdflow.yaml`을 만들며, 이 명령은 엔진을 호출하지 않고 기존 로스터를 덮어쓰지 않는다. `md init --guided`는 저장소 맞춤 설정 대화를, `md init --print-guide`는 같은 가이드를 출력한다. 설치형 스킬은 `npx skills add johnlindquist/mdflow`로 코딩 에이전트에 주입하고, 전역 CLI는 `npm install -g mdflow`로 둔다. 첫 사용은 `md doctor --json`(무료·정적·읽기 전용 진단), `md explain flows/ .md --json`, `md eval flows/ .md --plan` 순서로 상태를 확인하는 것이며, 인자 없는 `md`는 PROJECT·GLOBAL·INSTALLED·PATH 출처를 표시하는 검색 가능한 Flow Workbench를 연다.

전제와 한계

전제는 Node/npx 실행 환경과 Claude Code·Codex·Gemini·Copilot·opencode·pi 같은 CLI 엔진 중 하나다. 컨텍스트 격리는 엔진이 자체 플래그를 지원할 때만 적용되며(droid, cursor-agent, agy는 앰비언트로 실행되고 `_isolated: true` 명시 시에만 경고), 이 격리는 호스트 파일시스템·네트워크·프로세스·환경·자격증명 샌드박스가 아니다. 인라인 셸 명령은 플로우의 명시적 능력으로 남고, eval·hook 사이드카는 실행 가능한 로컬 코드이며, 레지스트리 설치는 플로우 하나를 추가할 뿐 사이드카를 신뢰하지 않는다. 시스템 프롬프트를 대체할 메커니즘이 없는 엔진은 프롬프트를 조용히 버리지 않고 실행을 실패시킨다.

관련 논문 4

유사 도구