MarkVibe Coding v0.1.0
New Paradigm — 2026

마크 바이브 코딩
소개

마크다운만으로 소프트웨어를 만들고, 글을 쓰고, 자료를 조사하고,
모든 업무를 수행하는 통합 워킹 스페이스.

Markdown Vibe Coding Theory Author: Leaf Edition: v0.1.0
Table of Contents / 목차
  1. 서론: 마크 바이브 코딩의 탄생 배경 Introduction
  2. 핵심 개념과 정의 Core Concepts
  3. 제로-터미널 원칙 Zero-Terminal Principle
  4. 워크플로우 — TODO 마크다운의 힘 Workflow
  5. 하네스 엔지니어링 Harness Engineering
  6. 실무 적용 가이드 Practical Guide
  7. 유사 방법론과의 비교 Related Methodologies
  8. 결론: 코딩 없는 코딩의 미래 Conclusion
Introduction

서론: 마크 바이브 코딩의 탄생 배경 The Birth of MarkVibe Coding

바이브 코딩에서 마크 바이브 코딩으로

2025년, 바이브 코딩(Vibe Coding)이라는 용어가 개발자 커뮤니티를 뜨겁게 달궜다. Andrej Karpathy가 제안한 이 개념은 "코드를 직접 작성하기보다 AI에게 원하는 바를 전달하고, 결과물의 '분위기(vibe)'만 확인하면 된다"는 파격적인 접근이었다.

In 2025, "Vibe Coding" — coined by Andrej Karpathy — swept the developer community. The idea: instead of writing code directly, describe what you want to an AI agent and verify the output's "vibe."

하지만 바이브 코딩에는 본질적인 한계가 있었다. 개발자는 여전히 IDE를 열고, 터미널에서 명령어를 입력하고, 여러 도구를 오가며 에이전트와 소통해야 했다. 인터페이스가 분산된 상태에서는 컨텍스트 스위칭 비용이 발생하고, 에이전트에게 전달되는 의도의 일관성이 깨진다.

💡
핵심 통찰 / Key Insight 바이브 코딩의 다음 단계는 "도구의 제거"다. 인터페이스를 마크다운이라는 단일 매체로 통합하면, 인간과 에이전트 사이의 의사소통 채널이 하나로 수렴한다.

마크 바이브 코딩(MarkVibe Coding)은 이 통찰에서 출발한다. 모든 설계, 지시, 검증, 기록의 매체를 마크다운(.md)으로 단일화하고, 개발자가 터미널이나 IDE에 직접 접근하는 행위를 원칙적으로 금지한다. 에이전트를 시작할 때 전달하는 것은 오직 마크다운 파일의 경로뿐이다.

MarkVibe Coding unifies every development interface — design, instruction, verification, logging — into a single medium: Markdown. The developer never opens a terminal or IDE. The only thing passed to the agent is a file path.

Chapter 01

핵심 개념과 정의 Core Concepts and Definitions

마크 바이브 코딩의 정의

"마크 바이브 코딩이란, 마크다운을 유일한 인터페이스로 삼아 소프트웨어 개발, 문서 작성, 자료 조사, 그리고 모든 업무를 수행하는 통합 워킹 스페이스 방법론이다. 작업자는 입력과 출력만 마크다운으로 확인하며, MARKVIBE.md는 그 경로, 범위, 관계, 권한을 정의해둔다."

— MarkVibe Coding Manifesto, 2026

"MarkVibe Coding is a unified working space methodology where software development, writing, research, and all work is performed through Markdown as the sole interface. The practitioner checks only Input and Output in Markdown, with MARKVIBE.md defining their paths, scope, relationships, and permissions."

8대 원칙 (Eight Pillars)

Principle 01

Markdown-Centric

모든 설계, 구현 지시, 테스트 보고는 마크다운 파일로만 수행된다. 코드를 직접 편집하지 않는다.

Principle 02

Zero-Terminal

터미널을 열지 않는다. 마크다운 에디터가 에이전트와 직접 연결되어, 문서 저장만으로 모든 것이 End-to-End로 완결된다.

Principle 03

Single Document

하나의 문서 안에서 모든 것을 완성한다. 문서를 옮겨 다니지 않는다. 요청, 결과, 추가 요구사항이 한 파일에 누적된다.

Principle 04

Seed TODO

인간은 최초의 씨앗 TODO(Seed TODO)만 작성한다. 에이전트는 결과만 보고하고, 추가 요구사항은 같은 문서에 이어 적는다.

Principle 05

Structural Diff

마크다운의 구조(제목, 리스트, 들여쓰기)를 활용해 변경된 지시사항만 정확히 추출하여 에이전트에 전달한다. 전체 문서가 아닌 변경분만 전송하므로 토큰을 절약하고, 긴 문서에서도 효율적인 입력이 가능하다.

Principle 06

Accumulated Changelog

각 지시의 결과는 하나의 파일에 CHANGELOG처럼 계속 누적된다. 에디터가 에이전트의 출력을 실시간 스트리밍 렌더링하여, 결과가 문서에 즉시 반영되는 것을 사용자가 눈으로 확인한다.

Principle 07

Markdown State Management

모든 문서 상태를 대시보드 형태로 보여준다. 인간의 승인이 필요한 항목(배포, 머지, 삭제 등)도 대시보드에 남기고 승인/거부를 기록한다. 평가 완료된 문서는 아카이브로 이동하고, 활성 문서만 워크스페이스에 남긴다.

Principle 08

Agent-Harness Synergy

에이전트는 하네스(Harness)를 스스로 구축하고, 코드의 안정성을 자동 검증하며, 결과를 문서에 기록한다.

핵심 구성 요소

마크다운 파일
TODO.md, CLAUDE.md, MARKVIBE.md, DESIGN.md 등 — 인간과 에이전트 사이의 유일한 의사소통 채널.
코드 에이전트
Claude Code, OpenAI Codex 등 — 마크다운을 읽고 코드를 생성·수정·실행하는 자율 시스템.
하네스 (Harness)
에이전트가 자체 구축하는 테스트·린트·빌드 파이프라인. 코드 품질을 자동 보장하는 안전장치.
마크다운 로그
에이전트의 모든 작업 과정이 기록되는 .md 파일. 감사(audit) 추적과 디버깅의 근거.

에이전트 지침 파일의 계보

마크 바이브 코딩은 독자적으로 등장한 것이 아니라, AI 에이전트 생태계의 지침 파일(Instruction File) 패러다임 위에서 탄생했다.

파일 플랫폼 역할
AGENTS.md OpenAI Codex 프로젝트 빌드 규칙, 테스트 명령, 구조 가이드
CLAUDE.md Claude Code 프로젝트 지침, 코딩 표준, 아키텍처 결정 사항
DESIGN.md Google Stitch 화면 디자인 — 색상, 타이포그래피, 컴포넌트, 레이아웃 스타일
MARKVIBE.md MarkVibe 위 세 가지를 통합하는 마크 바이브 코딩 전용 지침

MarkVibe Coding builds on the "instruction file" paradigm: AGENTS.md (OpenAI), CLAUDE.md (Anthropic), DESIGN.md (Google Stitch). MARKVIBE.md unifies them into a single specification for the MarkVibe workflow.

Chapter 02

제로-터미널 원칙 The Zero-Terminal Principle

왜 터미널 입력을 금지하는가?

전통적 개발에서 터미널은 만능 도구였다. 하지만 마크 바이브 코딩은 터미널 접근을 원칙적으로 금지한다. 이것은 단순한 제약이 아니라, 추상화 수준(Abstraction Level)을 일관되게 유지하기 위한 설계적 결정이다.

⚠️
제로-터미널 규칙 / Zero-Terminal Rule CLI에 입력하는 것은 오로지 에이전트 시작 시 마크다운 파일 경로뿐이다.
claude ".markvibe/active/login.md를 참고해서 작업을 진행하세요."
이 한 줄 외에 어떠한 터미널 명령도 허용되지 않는다.

추상화 레벨의 유지

소프트웨어 공학에서 추상화 수준이 혼재되면 복잡성이 기하급수적으로 증가한다. 마크 바이브 코딩에서 인간의 추상화 레벨은 오직 "의도(Intent)"이다.

레이어 전통 개발 바이브 코딩 마크 바이브 코딩
의도 전달 구두, 이슈, 문서 프롬프트 (채팅) TODO.md
설계 IDE, Figma, 위키 프롬프트 + IDE DESIGN.md
구현 IDE에서 직접 코딩 AI 생성 + 수동 편집 에이전트 자율 수행
실행/빌드 터미널 명령어 터미널 명령어 에이전트 자율 수행
검증 수동 테스트 수동 + AI 보조 하네스 자동 검증
인터페이스 수 5개 이상 3~4개 1개 (마크다운)

유일한 예외: 에이전트 시작

제로-터미널 원칙에는 단 하나의 예외가 존재한다. 에이전트를 최초 실행할 때 마크다운 파일 경로를 전달하는 행위다. 이후의 모든 상호작용 — 추가 요청, 수정 지시, 버그 보고 — 은 마크다운 파일을 수정하는 것으로만 이루어진다.

Terminal — 유일하게 허용되는 입력
# 에이전트 시작 (이것이 유일한 터미널 입력)
$ claude ".markvibe/active/login.md를 참고해서 작업하세요."

# 이후 추가 요청이 필요하면?
# → 터미널에 입력하지 않는다
# → TODO.md를 수정하고 저장한다
# → 에이전트가 파일 변경을 감지하고 자율 대응한다

The Zero-Terminal Principle permits exactly one terminal interaction: passing a Markdown file path to start the agent. Every subsequent request — modifications, bug reports, design changes — is communicated by editing the Markdown file. The agent watches for changes and responds autonomously.

Chapter 03

워크플로우 — 단일 문서의 힘 Workflow: The Power of a Single Document

핵심: 하나의 문서에서 모든 것을 끝낸다

마크 바이브 코딩의 워크플로우는 놀라울 정도로 단순하다. 인간은 하나의 마크다운 파일만 열어두고, 그 안에서 요청하고, 결과를 확인하고, 추가 요구사항을 적고, 다시 결과를 확인한다. 문서를 옮겨 다니지 않는다. 터미널을 열지 않는다. 문서 저장만으로 모든 것이 End-to-End로 완결된다.

The workflow is remarkably simple. The human opens a single Markdown file — requests, results, follow-up requirements, and results again all live in that one file. No switching between documents. No terminal. Save the file, and everything runs End-to-End.

Seed TODO — 씨앗 하나로 시작한다

인간이 최초에 작성하는 것은 Seed TODO — 프로젝트의 씨앗이 되는 최소한의 의도이다. 이것이 문서의 시작점이자 전체 프로젝트의 원점이다. 에이전트는 이 씨앗을 받아 개발을 수행하고, 같은 문서에 결과만 보고한다.

login.md — Seed TODO (인간이 최초 작성)
# 사용자 로그인 페이지

## Seed TODO
- 기능: OAuth 2.0 기반 로그인 (Google, GitHub)
- 스택: React + Express.js + Passport.js
- 디자인: DESIGN.md 참고
- 테스트: Jest 단위 테스트 포함

결과 보고 — 같은 문서에 누적된다

에이전트가 작업을 완료하면, 같은 파일에 결과를 추가한다. 별도의 LOG.md로 분산하지 않는다. 하나의 문서가 CHANGELOG처럼 작동한다.

login.md — 에이전트가 결과를 추가한 상태
# 사용자 로그인 페이지

## Seed TODO
- 기능: OAuth 2.0 기반 로그인 (Google, GitHub)
- 스택: React + Express.js + Passport.js
- 디자인: DESIGN.md 참고
- 테스트: Jest 단위 테스트 포함

## Result — 2026-04-05 14:30
- 생성: src/pages/Login.tsx, src/api/auth.ts, src/middleware/passport.ts
- 테스트: 12/12 통과
- 로그: → .markvibe/archive/2026-04-05-login.md (경로만 기록)
- 상태: 완료

추가 요구사항 — 같은 문서에 이어 적는다

새로운 요구사항이 생기면, 같은 문서의 아래에 이어서 적는다. 이전 상태(Seed TODO + Result)가 이미 기록되어 있으므로, 에이전트는 맥락을 완전히 파악한 채로 추가 작업을 수행할 수 있다.

login.md — 인간이 추가 요구사항을 작성
# 사용자 로그인 페이지

## Seed TODO
- 기능: OAuth 2.0 기반 로그인 (Google, GitHub)
- 스택: React + Express.js + Passport.js
- 디자인: DESIGN.md 참고
- 테스트: Jest 단위 테스트 포함

## Result — 2026-04-05 14:30
- 생성: src/pages/Login.tsx, src/api/auth.ts, src/middleware/passport.ts
- 테스트: 12/12 통과
- 상태: 완료

───────────────────────────────

## 추가 요청 — 2026-04-05 15:00
- 변경: Apple 로그인도 추가해줘
- 조건: 기존 Google/GitHub 로직과 동일한 패턴 유지

Structural Diff — 토큰을 절약하는 구조적 변경 감지

이것이 마크 바이브 코딩의 핵심 메커니즘이다. 마크다운은 본래 구조화된 문서이다. 제목(##), 리스트(-), 들여쓰기로 계층 정보를 담고 있다. 에이전트(또는 마크다운 에디터)는 이 구조를 읽어서:

를 자동으로 구분할 수 있다. 마크다운의 구조성 자체가 DIFF 역할을 한다.

핵심은 토큰 효율이다. 문서가 수백 줄로 누적되어도, 에디터는 전체 문서를 에이전트에 보내지 않는다. 마크다운 구조를 파싱하여 변경된 지시사항만 추출해서 전달한다. 예를 들어, ## 추가 요청 헤딩 아래에 새로 추가된 - 항목 2줄만 전송하면 된다. 이전 Seed TODO와 Result는 이미 처리 완료되었으므로 재전송할 필요가 없다. 이 방식으로 긴 누적 문서에서도 최소한의 토큰으로 정확한 입력이 가능하다.

🧩
Structural Diff의 원리 ## Seed TODO 아래의 - 항목은 원본 요청이다. ## Result 아래의 - 항목은 에이전트의 보고이다. ## 추가 요청이라는 새 헤딩이 나타나면 신규 요청이다. 에디터는 구조적 변경분만 추출하여 에이전트에 전달한다 — 전체 문서를 재전송하지 않는다.

전체 흐름 — End-to-End in One File

Single Document Lifecycle
Seed TODO 작성
→
에이전트 실행
→
Result 추가
→
추가 요청 작성
→
Diff 감지 & 실행
→
Result 누적

이 사이클이 하나의 파일 안에서 무한 반복된다. 파일은 자연스럽게 CHANGELOG가 된다.

누적되는 문서 = 살아있는 CHANGELOG

시간이 지나면 하나의 문서에는 Seed TODO, 첫 번째 Result, 추가 요청, 두 번째 Result...이 계속 쌓인다. 이 문서 자체가 프로젝트의 전체 이력이자 CHANGELOG가 된다. 별도의 로그 파일을 만들 필요가 없다.

이 과정에서 마크다운 에디터는 실시간 스트리밍 렌더링을 수행한다. 에이전트가 Result를 생성하는 순간, 에디터 화면에 마크다운이 즉시 렌더링되어 나타난다. 사용자는 터미널 로그를 기다리는 것이 아니라, 문서가 실시간으로 채워지는 것을 눈으로 확인한다. 이것이 마크 바이브 코딩의 사용자 경험이다.

login.md — 시간이 지난 후 (누적된 상태)
# 사용자 로그인 페이지

## Seed TODO
- 기능: OAuth 2.0 기반 로그인
- ...

## Result — 2026-04-05 14:30
- 상태: 완료 (Google, GitHub 로그인)

## 추가 요청 — 2026-04-05 15:00
- Apple 로그인 추가

## Result — 2026-04-05 15:45
- 상태: 완료 (Apple 로그인 추가)

## 추가 요청 — 2026-04-06 09:00
- 로그인 실패 시 에러 메시지 개선
- 비밀번호 찾기 플로우 추가

## Result — 2026-04-06 10:20
- 상태: 완료 (에러 UX 개선 + 비밀번호 찾기)
- 테스트: 28/28 통과
⚠️
절대 하지 않는 것 • 새 요구사항을 위해 새 파일을 만들지 않는다 — 같은 문서에 이어 적는다
• 터미널을 열어서 에이전트에게 직접 말하지 않는다 — 문서를 저장한다
• 결과를 별도 로그 파일에 분리하지 않는다 — 같은 문서에 누적하되, 참조가 필요한 산출물은 경로만 기록한다

마크다운 상태 관리 — 핵심 메커니즘

마크 바이브 코딩에서 가장 중요한 개념은 마크다운의 상태(State)를 관리하는 것이다. 모든 문서는 active 또는 archive 두 가지 상태만 가진다.

통계적 결과만 남긴다

에이전트는 작업 과정의 모든 디테일을 문서에 쏟아붓지 않는다. 사용자에게는 통계적 결과 — 테스트 통과율, 생성 파일 수, 변경 요약 — 만 기록한다. 인간이 판단하기에 필요한 최소한의 정보만 마크다운에 남긴다.

대시보드 — 모든 상태를 한눈에

마크다운 상태 관리의 최종 형태는 대시보드이다. 에디터(또는 워크스페이스 뷰)는 active/에 있는 모든 문서의 상태를 대시보드 형태로 보여준다. 각 문서의 진행률, 최근 Result, 다음 TODO가 한눈에 보인다.

특히 인간의 승인이 필요한 항목 — 프로덕션 배포, 브랜치 머지, 파일 삭제, 외부 API 호출 같은 위험한 작업 — 도 대시보드에 명시적으로 표시된다. 인간은 대시보드에서 승인/거부를 결정하고, 그 판단이 문서에 기록된다. 에이전트가 자율적으로 수행할 수 없는 작업의 승인 흐름까지 마크다운 안에서 완결된다.

유용성 평가 → 아카이브

문서의 모든 TODO가 완료되고 결과가 검증되면, 해당 문서는 유용성 평가를 거친다. "이 문서가 앞으로도 참조 가치가 있는가?"를 판단하고, 평가가 완료되면 archive/로 이동한다. 워크스페이스에는 현재 활성화된 마크다운만 남는다.

Markdown State Lifecycle
Seed TODO 작성
→
active/login.md
→
작업 & 결과 누적
→
유용성 평가
→
archive/login.md
.markvibe/ — 상태 기반 디렉터리
.markvibe/
├── active/              # 현재 진행 중인 문서만 존재
│   ├── login.md         # 진행 중 — Seed + Result 누적 중
│   └── dashboard.md     # 진행 중
│
└── archive/             # 평가 완료된 문서
    ├── onboarding.md    # 완료 — 통계 결과만 남음
    └── auth-refactor.md # 완료 — 참조용 아카이브
login.md — 승인 요청이 ��함된 문서
## Result — 2026-04-05 16:00
- 생성: src/deploy/production.ts
- 테스트: 28/28 통과

## Approval Required
- 작업: 프로덕션 배포 (main → production)
- 위험도: HIGH
- 대상: v1.2.0 릴리스
- 승인: [ ] 승인 / [ ] 거부

───────────────────────────────

## Approval — 2026-04-05 16:15
- 판단: 승인
- 사유: 테스트 전체 통과, 스테이징 검증 완료
📋
상태 관리의 핵심 규칙 • active/에는 현재 작업 중인 문서만 둔다 — 적을수록 좋다
• 에이전트는 사용자에게 통계적 요약만 보고한다 (파일 수, 테스트 결과, 변경 요약)
• TODO가 모두 완료되면 유용성을 평가하고 archive/로 이동한다
• archive의 문서는 읽기 전용이다 — 수정이 필요하면 active로 복귀시킨다
• 워크스페이스를 항상 깨끗하게 유지하는 것이 마크 바이브의 핵심이다
Chapter 04

하네스 엔지니어링 Harness Engineering

하네스란 무엇인가?

2026년 2월, OpenAI의 Ryan Lopopolo는 "하네스 엔지니어링(Harness Engineering)"이라는 개념을 블로그에서 상세히 소개했다. 그 핵심 논지를 요약하면 다음과 같다:

Agent = Model + Harness

— Ryan Lopopolo의 핵심 논지를 요약한 공식. 원문: "Harness Engineering: Leveraging Codex in an Agent-First World" (2026.02, OpenAI Blog)

하네스(Harness)란 AI 코딩 에이전트에서 모델을 제외한 모든 것 — 오케스트레이션 로직, 컨텍스트 관리, 아키텍처 제약, 테스트 파이프라인, 리뷰 시스템 — 을 의미한다. Thoughtworks의 Birgitta Boeckeler는 이를 "에이전트의 행동을 예측하고 교정하는 가이드(Feedforward)와 센서(Feedback)의 조합"으로 정리했다(martinfowler.com 게재).

In February 2026, OpenAI's Ryan Lopopolo formalized "Harness Engineering" — where the harness is everything in an AI agent except the model itself: orchestration, context management, architectural constraints, test pipelines, and review systems.

OpenAI의 실험 결과

OpenAI는 하네스 엔지니어링으로 내부 프로젝트를 수행하며 다음 성과를 공개했다:

지표수치
코드 규모약 100만 줄의 프로덕션 코드
팀 규모초기 3명의 엔지니어 (이후 7명으로 확장)
Pull Requests총 1,500건 생성·머지
개발 속도엔지니어 1인당 하루 3.5건 PR
효율수동 대비 약 1/10 시간으로 완성
인간 작성 코드0줄 — 모든 코드를 Codex 에이전트가 생성

하네스의 3계층 구조

Birgitta Boeckeler(Thoughtworks)의 분류에 따르면, 하네스는 세 가지 규제 범주로 나뉜다:

Layer 1 — Maintainability

유지보수성 하네스

린터, 포매터, 타입 체커 등 결정론적(Computational) 도구로 코드 품질과 내부 구조를 보장한다. 가장 성숙한 영역.

Layer 2 — Architecture Fitness

아키텍처 적합성 하네스

의존성 레이어링(Types → Config → Repo → Service → Runtime → UI)을 강제하는 구조적 테스트. 모듈 간 계층 위반을 자동 감지한다.

Layer 3 — Behaviour

행동 하네스

기능적 정확성을 검증한다. AI 생성 테스트 + 수동 테스트에 의존하는 가장 미성숙한 영역이며, 앞으로 가장 많은 발전이 필요하다.

OpenAI의 하네스 핵심 기법

AGENTS.md as Map
~100줄의 간결한 파일로 유지. 거대한 지침 덤프가 아니라, 깊은 정보원을 가리키는 목차(Table of Contents) 역할. 컨텍스트는 희소 자원이므로 낭비하지 않는다.
Depth-First
큰 목표를 작은 빌딩 블록으로 분해하고, 각 블록을 완성한 뒤 다음 블록에 활용하는 깊이 우선 워크플로우.
Dependency Layering
Types → Config → Repo → Service → Runtime → UI 순서의 의존성 계층을 강제하고, 구조적 테스트로 준수 여부를 검증.
Garbage Collection
백그라운드 Codex 태스크가 주기적으로 코드 품질을 스캔하고 리팩토링 PR을 자동 생성. 이전에는 매주 금요일(20%)을 수동 정리에 소비했던 것을 대체.
Agent Self-Review
Codex가 자체 변경을 로컬에서 리뷰하고, 추가 에이전트 리뷰를 요청하며, 피드백에 응답하고, 모든 리뷰어가 승인할 때까지 반복.

마크 바이브 코딩에서의 하네스

마크 바이브 코딩은 OpenAI의 하네스 엔지니어링 개념을 수용하되, 핵심적인 차이가 있다.

⚠️
하네스는 미리 정의된 고정물이 아니다 일반적인 하네스 엔지니어링에서는 팀이 하네스를 사전에 설계하고 고정한다. 마크 바이브 코딩에서 하네스는 다르다. 하네스는 에이전트가 자율적으로 구축하고, 마크다운 문서를 통해 인간이 관리·제어하며, 반복적인 피드백 사이클을 거쳐 지속적으로 안정화·개선되는 살아있는 대상이다.

하네스의 생애주기 — 구축, 관리, 안정화

마크 바이브 코딩에서 하네스는 세 단계의 생애주기를 가진다:

구축 — 에이전트가 스스로 만든다

인간은 하네스를 직접 작성하지 않는다. Seed TODO에 "테스트를 포함해"라고 한 줄만 적으면, 에이전트가 프로젝트의 스택과 구조를 분석하여 린터 설정, 테스트 프레임워크, 아키텍처 검증 규칙을 스스로 구축한다. 하네스의 초기 형태는 에이전트의 판단에 의해 결정된다.

관리 — 마크다운으로 제어한다

하네스의 결과는 마크다운 문서에 보고된다. 인간은 문서를 통해 하네스의 상태를 확인하고, 부족한 부분이 있으면 추가 요청을 같은 문서에 이어 적는다. "Layer 3 커버리지가 너무 낮아, 엣지 케이스 테스트 추가해" 같은 지시가 하네스를 점진적으로 강화한다. 하네스 설정 자체도 마크다운으로 관리되므로, 인간은 코드를 읽지 않고도 하네스를 제어할 수 있다.

안정화 — 반복하며 개선된다

하네스는 한 번 만들면 끝나는 것이 아니다. 프로젝트가 진화하면 하네스도 함께 진화한다. 새로운 기능이 추가되면 테스트가 확장되고, 아키텍처가 변경되면 적합성 규칙이 갱신되며, 버그가 발견되면 하네스에 회귀 테스트가 추가된다. 이 모든 과정이 마크다운 문서의 요청-결과 사이클 안에서 이루어진다. 하네스는 사용할수록 더 단단해지는 누적적 자산이다.

login.md — 하네스가 진화하는 과정
## Seed TODO
- 기능: OAuth 2.0 로그인
- 테스트: 포함

## Result — 2026-04-05 14:30
- 하네스 Layer 1: ESLint 0 errors, Prettier 적용 완료
- 하네스 Layer 2: 의존성 계층 위반 0건
- 하네스 Layer 3: 12/12 테스트 통과
- 상태: 완료

## 추가 요청 — 2026-04-06 09:00
# 인간이 하네스를 제어한다
- 하네스 개선: 토큰 만료 시나리오 테스트 추가
- 하네스 개선: 동시 로그인 제한 검증 추가

## Result — 2026-04-06 10:20
- 하네스 Layer 3: 18/18 테스트 통과 (+6 신규)
- 추가된 테스트: 토큰 만료, 리프레시, 동시 세션, 잘못된 토큰, CSRF, Rate Limit
- 상태: 완료 — 하네스 강화됨
🔁
하네스 ≠ 고정된 설정 파일 전통적인 CI/CD 파이프라인은 한 번 구성하면 거의 변하지 않는다. 마크 바이브의 하네스는 다르다. 매번의 요청-결과 사이클에서 하네스가 함께 갱신된다. 인간은 마크다운으로 "이 부분을 더 엄격하게" 혹은 "이 검증은 불필요하니 제거해"라고 지시하고, 에이전트가 하네스를 즉시 반영한다. 하네스는 프로젝트와 함께 성장하는 동적인 품질 보장 체계이다.
✅
하네스의 핵심 가치 하네스는 "인간이 코드를 검토하지 않아도 된다"는 마크 바이브 코딩의 전제를 가능하게 하는 핵심 장치다. OpenAI의 실험이 증명하듯, 3명의 엔지니어가 100만 줄의 코드를 인간 작성 0줄로 완성할 수 있었던 것은 하네스가 품질을 자동으로 보장했기 때문이다. 마크 바이브 코딩은 여기에 한 가지를 더한다 — 하네스 자체를 마크다운으로 관리함으로써, 인간이 코드를 모르더라도 하네스를 제어하고 개선할 수 있다는 점이다.
Chapter 05

실무 적용 가이드 Practical Implementation Guide

권한 계층 — MARKVIBE.md는 최상위 지시

Authority Hierarchy
MARKVIBE.md
→
CLAUDE.md
/
AGENTS.md
/
.cursorrules

MARKVIBE.md는 특정 에이전트에 종속되지 않는 인간의 최상위 지시(Human Top-Level Directive)이다. CLAUDE.md는 Claude를, AGENTS.md는 Codex를 위한 것이지만, MARKVIBE.md는 인간을 위한 것이다.

MARKVIBE.md가 관리하는 것은 두 가지 메타정보뿐이다:

MARKVIBE.md는 프로젝트의 세부 코딩 규칙이나 스타일 가이드를 직접 담지 않는다. 그것은 각 에이전트의 고유 지침 파일의 영역이다. MARKVIBE.md는 그 파일들의 위치와 우선순위만 정의하는 메타 레이어이며, 충돌 시 항상 우선한다.

마크바이브 에디터 — 설계 철학

마크다운은 단순하다. 누구나 읽을 수 있고, 어디서든 열 수 있다. 마크 바이브 코딩을 위한 에디터도 이 원칙을 그대로 따른다. 에디터의 핵심은 인간 친화적인 인터페이스를 기초로 하여, 마크다운이 지식의 정리 수단이 되고, 그 자체로 일의 마침이 되는 방식을 실현하는 것이다.

마크다운이 단순한 철학인 것처럼, 마크 바이브 에디터도 단순한 형태로 개발하되 에이전트들과 함께 동작하는 것을 지원한다.

느슨한 연결 — 에이전트를 가두지 않는다

마크 바이브 에디터의 핵심 설계 원칙은 느슨한 연결(Loose Coupling)이다. Claude Code, Codex CLI 등 에이전트의 CLI 인터페이스와 느슨하게 연결할 뿐, 에이전트를 에디터 안에 가두는 방식이 아니다. 에이전트는 독립적으로 동작하는 외부 프로세스이고, 에디터는 마크다운 파일이라는 매체를 통해 에이전트와 소통한다. 에이전트가 바뀌어도 에디터는 그대로이고, 에디터가 바뀌어도 에이전트는 그대로이다.

⚠️
VS Code의 한계 VS Code는 마크다운 편집을 지원하지만, 마크 바이브 워크플로우를 구현하려면 Structural Diff 감지, 상태 관리, 에이전트 연동, 대시보드 등을 위한 지나치게 복잡한 플러그인 조합이 필요하다. 본래 코드 편집기인 VS Code 위에 마크 바이브의 문서 중심 워크플로우를 얹는 것은 도구의 본질과 맞지 않는다. 일반 사용자에게는 특히 진입 장벽이 높다.

두 가지 모드

사용자의 목적에 따라 두 가지 모드로 구분된다:

일반 모드 (General Mode) — 지식 관리

마크다운으로 노트, 자료 조사, 보고서, 프로젝트 관리를 수행하는 모드이다. 코딩 없이 문서 기반 업무에 집중한다. Seed TODO와 Result 누적, active/archive 상태 관리 등 마크 바이브의 기본 워크플로우를 지원한다. 프로그래밍 지식이 없는 사용자도 마크다운만 알면 사용할 수 있다.

전문가 모드 (Expert Mode) — 코딩 및 심화 작업

소프트웨어 개발, 하네스 엔지니어링, 멀티 에이전트 라우팅 등 전문적인 개발 워크플로우를 처리하는 모드이다. Structural Diff 감지, 에이전트 실시간 스트리밍 렌더링, 승인 플로우, 대시보드 등 마크 바이브의 Full Spec을 지원한다.

🔄
모드 선택 기준 단순 지식 관리·문서 업무라면 일반 모드, 코딩·배포·하네스 구성 등 전문 작업이라면 전문가 모드. 하나의 에디터에서 목적에 따라 전환한다.

호환 에디터 — Leaf Editor 외에도 가능하다

마크 바이브 코딩은 특정 에디터에 종속되지 않는다. 마크다운이 표준이므로, 마크 바이브 워크플로우를 지원하는 에디터라면 무엇이든 사용할 수 있다. Obsidian 같은 기존 에디터도 플러그인이나 커뮤니티 확장을 통해 마크 바이브 호환성을 확보할 수 있다.

📝
  • Obsidian — 파일 간 링크, 그래프 뷰로 문서 관계 시각화. 플러그인 생태계를 통해 active/archive 상태 관리, 에이전트 연동 등 마크 바이브 워크플로우 확장 가능. 일반 모드 지식 관리에 강점
  • Typora — 실시간 렌더링, WYSIWYG 편집. 일반 모드 지식 관리에 적합
  • Mark Text — 오픈소스, 깔끔한 인터페이스 (개발 비활성 상태이나 기존 버전 사용 가능)

Leaf Editor — 마크바이브 네이티브 에디터

🌿
Leaf Editor — 개발 중
마크 바이브 코딩 워크플로우를 네이티브로 지원하는 전용 에디터. 일반 모드와 전문가 모드를 모두 내장하며, 목적에 따라 자유롭게 전환할 수 있다. 에이전트를 에디터 안에 가두지 않고, Claude Code 등 외부 CLI와 느슨하게 연결하여 함께 동작한다. 에디터는 단순하고, 에이전트는 독립적이며, 마크다운이 둘을 잇는다. 초기 버전에서는 일반 모드(지식 관리)와 마크바이브 기본 스펙(Seed TODO, Result 누적, Structural Diff 감지)을 우선 구현하며, 전문가 모드의 Full Spec(대시보드, 승인 플로우, 멀티 에이전트 라우팅)은 이후 단계적으로 추가될 예정이다.
@leafeditor
Chapter 06

유사 방법론과의 비교 Related Methodologies & How MarkVibe Differs

마크 바이브 코딩은 갑자기 등장한 것이 아니다. 소프트웨어 공학의 역사에는 "코드를 작성하기 전에 무엇을 먼저 작성할 것인가"라는 질문에 대한 다양한 답이 존재해왔다. 이 장에서는 마크 바이브 코딩의 계보를 이루는 주요 방법론을 시대순으로 정리하고, 각각과의 차이를 명확히 한다.

1. Literate Programming / 문학적 프로그래밍 (1984)

Donald Knuth가 제안한 패러다임으로, 코드를 자연어 서사 안에 삽입하여 "프로그램을 문학처럼 읽을 수 있게" 만드는 것이 핵심이다. WEB 시스템으로 구현되었고, 현대의 Jupyter Notebook이 이 개념의 후손이다.

↔️
MarkVibe와의 차이 문학적 프로그래밍은 코드와 산문을 섞는다. 인간이 코드를 작성한다. 마크 바이브 코딩은 산문만 작성하고 코드는 에이전트에게 완전히 위임한다.

2. Behavior-Driven Development / BDD (2006)

Dan North가 제안한 방법론으로, Given-When-Then 형식의 Gherkin 구문으로 행동 명세를 작성하고, Cucumber 같은 도구가 이를 실행 가능한 테스트로 변환한다. 비즈니스 이해관계자와 개발자 사이의 의사소통 도구로 설계되었다.

↔️
MarkVibe와의 차이 BDD는 구조화된 제약 언어(Gherkin)를 사용하고, 명세 자체가 실행 가능한 테스트다. 마크 바이브 코딩은 자유 형식의 자연어(마크다운)를 사용하며, 실행은 AI 에이전트가 해석하여 수행한다.

3. README-Driven Development / RDD (2010)

GitHub 공동창업자 Tom Preston-Werner가 제안한 접근으로, 코드를 작성하기 전에 README를 먼저 완성하는 것이다. "README로 설명할 수 없다면, 설계가 너무 복잡한 것이다"라는 원칙을 따른다.

↔️
MarkVibe와의 차이 RDD의 마크다운은 인간 개발자를 위한 설계 사고 도구다. 마크 바이브 코딩의 마크다운은 AI 에이전트를 위한 실행 지시서다. RDD에서 인간은 README를 쓴 뒤 코드를 직접 작성한다. 마크 바이브에서는 작성하지 않는다.

4. Spec-Driven Development / 스펙 주도 개발 (2011~)

OpenAPI(Swagger) 명세를 먼저 작성하고, 그 스펙으로부터 서버 스텁, 클라이언트 SDK, 문서, 테스트를 자동 생성하는 방법론이다. API 계약(Contract)이 모든 구현의 단일 진실 원천(Single Source of Truth)이 된다.

↔️
MarkVibe와의 차이 스펙 주도 개발의 명세는 기계 판독 가능한 스키마(YAML/JSON)이다. 마크 바이브 코딩의 명세는 자연어 마크다운이다. 스펙 주도 개발은 결정론적 코드 생성 도구를 사용하고, 마크 바이브는 AI 에이전트의 해석에 의존한다.

5. Design Doc Driven Development / Google 설계 문서 (2000s~)

Google, Uber 등 대형 테크 기업에서 실천하는 방법론으로, 구현 전에 배경, 목표, 비목표, 제안 솔루션, 대안, 트레이드오프를 담은 설계 문서를 작성하고 동료 리뷰를 거친다. 보통 2~20페이지 분량이다.

↔️
MarkVibe와의 차이 설계 문서는 인간 엔지니어가 리뷰하고 합의하는 협업 도구다. 마크 바이브의 TODO.md는 에이전트에게 전달되는 실행 지시다. 설계 문서는 "왜"에 집중하고, TODO.md는 "무엇을"에 집중한다.

6. Harness-Driven Development / 하네스 주도 개발 (2021~2023)

HumanEval, MBPP(2021), SWE-bench(2023) 등 AI 코딩 벤치마크에서 핵심적으로 사용되는 접근으로, 실패하는 테스트 스위트(하네스)를 먼저 정의하고 AI 에이전트가 이를 통과하는 코드를 생성하도록 한다. 성공 여부는 이진적이고 자동화된다.

↔️
MarkVibe와의 차이 하네스 주도 개발은 실행 가능한 테스트 코드가 명세다. 마크 바이브 코딩은 자연어 마크다운이 명세이고, 하네스는 에이전트가 자율적으로 구축하는 부산물이다. 마크 바이브는 하네스 개념을 수용하되, 인간이 하네스를 작성하지 않는다.

7. Vibe Coding / 바이브 코딩 (2025)

2025년 2월, AI 연구자 Andrej Karpathy(전 Tesla AI 수석 디렉터, OpenAI 초기 연구원)가 X(Twitter)에서 처음 명명한 개발 스타일이다.

"fully give in to the vibes, embrace exponentials, and forget that the code even exists."

— Andrej Karpathy, 2025년 2월

AI에게 대화체로 원하는 바를 전달하고, 생성된 코드를 상세히 검토하지 않은 채 수용하며, 버그가 생기면 에러 메시지를 그대로 붙여넣어 해결하는 방식이다. Cursor, Replit Agent, Claude Code 등의 도구가 주로 사용된다.

바이브 코딩은 폭발적으로 확산되었다. Y Combinator의 2025년 Winter 배치에서 스타트업의 25%가 코드베이스의 95%를 AI로 생성했다고 보고되었으며, Collins English Dictionary는 이를 2025년 올해의 단어로 선정했다. 한편 Merriam-Webster도 2025년 3월 "slang & trending"으로 등재했다.

그러나 심각한 문제도 드러났다. Lovable 플랫폼에서 1,645개 앱 중 170개에서 보안 취약점이 발견되었고(2025.05), Replit은 명시적 지시에도 불구하고 프로덕션 데이터베이스를 삭제하는 사고가 발생했다(2025.07). 2025년 12월 CodeRabbit 연구에 따르면, AI 공동 작성 코드는 인간 작성 코드보다 전체 이슈가 약 1.7배 더 많았으며, 보안 이슈는 최대 2.74배에 달했다. 이러한 한계가 스펙 주도 개발(SDD)과 하네스 엔지니어링 같은 보완 방법론의 등장을 촉발했다.

↔️
MarkVibe와의 차이 바이브 코딩은 비정형 대화로 이루어지며, 명세가 없고 버전 관리도 없다. 마크 바이브 코딩은 바이브 코딩의 속도를 유지하면서 구조, 경로, 추적 가능성, 하네스를 부여한다. 바이브 코딩이 "느낌"이라면, 마크 바이브 코딩은 "기록된 의도"이다. 바이브 코딩의 보안·품질 문제는 하네스가 해결하고, 의사결정 추적 문제는 단일 문서 누적 방식이 해결한다.

8. Agent Instruction Files / 에이전트 지침 파일 (2024~)

CLAUDE.md(Anthropic), AGENTS.md(OpenAI), DESIGN.md(Google Stitch), .cursorrules(Cursor) 등 AI 에이전트에게 프로젝트 컨텍스트를 전달하는 마크다운 파일 컨벤션이다. 저장소에 커밋되어 버전 관리되며, 인간과 AI 모두를 위한 이중 목적 문서로 기능한다.

↔️
MarkVibe와의 차이 에이전트 지침 파일은 각 에이전트에 종속된 설정이다. MARKVIBE.md는 이들 위에 놓이는 인간의 최상위 지시이며, 어떤 에이전트 조합을 사용하든 프로젝트의 의도와 구조를 통합적으로 정의한다.

전체 비교표

방법론 연도 명세 형식 소비자 실행 가능
Literate Programming 1984 WEB/noweb 인간 Yes
BDD / Gherkin 2006 Given-When-Then 인간 + 테스트 러너 Yes
README-Driven (RDD) 2010 Markdown 인간 No
Spec-Driven (SDD) 2011 YAML/JSON 코드 생성 도구 Yes
Design Doc Driven 2000s 산문 (Docs/MD) 인간 리뷰어 No
Harness-Driven 2021~2023 테스트 스위트 AI 에이전트 + CI Yes
Vibe Coding 2025 대화체 LLM LLM 해석
Agent Instruction Files 2024 Markdown AI 에이전트 + 인간 AI 해석
MarkVibe Coding 2026 Markdown (최상위) AI 에이전트 (모든 종류) AI 해석
📊
핵심 진화의 흐름 초기 방법론은 구조화된 문서를 인간이나 결정론적 도구에게 전달했다. 2024-2025년의 흐름은 마크다운을 인간과 AI 에이전트 양쪽을 위한 이중 목적 산출물로 사용한다. 마크 바이브 코딩은 이 흐름의 논리적 종착점 — 마크다운을 유일한 인터페이스로 삼고, 에이전트에 종속되지 않는 최상위 지시 체계를 구축한다.
Conclusion

결론: 코딩 없는 코딩의 미래 The Future of Codeless Coding

마크 바이브 코딩은 단순한 방법론이 아니다. 이것은 "개발자란 무엇인가"에 대한 재정의이다.

전통적 개발에서 개발자의 정체성은 "코드를 작성하는 사람"이었다. 바이브 코딩은 이를 "AI에게 지시하는 사람"으로 확장했다. 마크 바이브 코딩은 한 걸음 더 나아가, 개발자를 "의도를 구조화하는 사람"으로 재정의한다.

Traditional developers "write code." Vibe coders "instruct AI." MarkVibe coders "structure intent." The developer's role evolves from implementation to orchestration — from typing syntax to composing purpose.

"가장 좋은 코드는 작성하지 않아도 되는 코드다. 마크 바이브 코딩은 이 오래된 격언을 문자 그대로 실현한다."

마크 바이브 코딩이 가져올 변화

다음 단계: MarkVibe Working

마크 바이브 코딩은 최종 목적지가 아니다. 이것은 MarkVibe Working으로 가기 위한 전 단계다.

마크 바이브 코딩이 "마크다운으로 소프트웨어를 만드는 것"이라면, 마크 바이브 워킹은 "마크다운으로 모든 업무를 수행하는 것"이다. 코딩뿐 아니라 기획, 디자인, 마케팅, 자료 조사, 보고서 작성, 프로젝트 관리까지 — 모든 지식 노동이 마크다운 문서 하나로 수렴하는 미래.

마크 바이브 코딩이 먼저 정착해야 한다. 개발이라는 가장 복잡한 영역에서 "단일 문서 + AI 에이전트" 패턴이 검증되면, 그 패턴은 자연스럽게 다른 모든 업무 영역으로 확산될 것이다. 코딩이 증명의 장이고, 워킹이 최종 비전이다.

MarkVibe Coding is not the final destination — it is the stepping stone to MarkVibe Working, where all knowledge work — planning, design, marketing, research, reporting, project management — converges into a single Markdown document powered by AI agents. Coding is the proving ground; Working is the ultimate vision.

Evolution Path
Vibe Coding (2025)
→
MarkVibe Coding
→
MarkVibe Working
🚀
시작은 간단하다 1. 프로젝트에 MARKVIBE.md를 추가한다.
2. 하나의 .md 파일에 Seed TODO를 적는다.
3. 마크다운 에디터에서 저장한다.
4. 결과를 같은 문서에서 확인한다.
그것이 전부다.

Write Markdown. Build Software.

— MarkVibe Coding, 2026