FreeDoc

AI-first document anchor — 프로젝트 루트에 파일 하나, AI가 즉시 파악한다

npm install -g @jindolkim/freedoc
freedoc init

왜 필요한가

AI에게 프로젝트를 설명할 방법이 없다.

README는 인간용이다. AI는 100페이지 Markdown을 받아도:

• 현재 어디까지 왔는지 모른다
• 뭘 건드리면 안 되는지 모른다
• 이미 실패한 게 뭔지 모른다

결과: 매 대화마다 같은 설명 반복, 이미 실패한 방법 재시도.

FreeDoc은 이 문제를 해결한다.

설치

npm install -g @jindolkim/freedoc

빠른 시작

# 1. 프로젝트 폴더에서 템플릿 생성
cd my-project
freedoc init

# 2. FREEDOC.fds 편집 후 검증
freedoc validate

# 3. 특정 블록 읽기
freedoc read POSITION
freedoc read MAP

# 4. 전체 프로젝트 탐색 — 디렉토리 내 FREEDOC.fds 전부 스캔
freedoc search /your/projects

FREEDOC.fds 예시

FREEDOC {
  version: 1
  spec: "2026-05"
}

IDENTITY {
  what: my-project
  domain: web-backend
  lang: nodejs
}

POSITION {
  status: in_progress
  stage: "3/8"
  current: auth-module
  next: [payment, deploy]
}

MAP {
  entry: app/server.js
  db:    app/db.js
  auth:  app/auth.js
}

FIXED {
  port: 3000
  db:   sqlite
}

FAILURE {
  redis_cause: not-available-in-production
  redis_fixed: true
}

CONSTRAINT {
  rules: [no_orm, no_typescript, sqlite_only]
}

CLAIM {
  claims: [flat_is_better_than_nested, structure_beats_prose]
}

블록 설명

| 블록 | 필수 | 역할 | |------|------|------| | IDENTITY | ✅ | 프로젝트 정체성 | | POSITION | ✅ | 현재 진행 상태 | | MAP | ✅ | 파일 위치 지도 | | FIXED | — | 절대 바꾸면 안 되는 값 | | FAILURE | — | 이미 실패한 것 (반복 방지) | | CONSTRAINT | — | 금지 규칙 | | CLAIM | — | 핵심 주장 |

IDENTITY.what, POSITION.status, MAP.entry — 이 세 가지 없으면 validate 실패.

POSITION.status 는 enum 강제: todo / in_progress / done / blocked

작성 규칙

값은 코드처럼 — 문장 금지

what: "이 프로젝트는 결제 시스템입니다"  ← 틀림
what: payment-system                      ← 맞음

날짜/버전은 따옴표

spec: 2026-05    ← 파싱 실패
spec: "2026-05"  ← 올바름

50줄 이하

길면 AI도 안 읽는다.

Markdown과의 관계

둘은 대체 관계가 아니다. README는 그대로 쓰고 FREEDOC.fds를 추가한다.

| | Markdown | FreeDoc | |---|---|---| | 대상 | 인간 | AI | | 구조 | 자유형 | 강제 블록 | | 상태 표현 | 없음 | POSITION 필수 | | 실수 기록 | 없음 | FAILURE 블록 | | 파싱 | 어려움 | 즉시 JSON |

CLI 전체 명령

freedoc init              FREEDOC.fds 템플릿 생성
freedoc validate [file]   유효성 검사 (기본: ./FREEDOC.fds)
freedoc read <BLOCK>      특정 블록 JSON 출력
freedoc parse [file]      AST 전체 출력
freedoc search <dir>      디렉토리 내 전체 프로젝트 탐색

search 출력 예시

$ freedoc search /root/kim

[done]        bicycle-club       production     /root/kim/bicycle-club/FREEDOC.fds
[in_progress] freelang-v11       freedoc-integration  /root/kim/freelang-v11/FREEDOC.fds
[in_progress] freedoc            spec-finalization    /root/kim/freedoc/FREEDOC.fds
[done]        fishing-club-app   production     /root/kim/fishing-app/FREEDOC.fds
...

Total: 75

status, what, current, 경로 순으로 출력. grep으로 필터링 가능.

freedoc search /root/kim | grep done
freedoc search /root/kim | grep club
freedoc search /root/kim | grep in_progress

언어 독립

.fds 포맷은 어떤 언어로도 구현 가능하다. 이 패키지는 Node.js 레퍼런스 구현체 (npm 의존성 0개).

npm · npmjs.com/package/@jindolkim/freedoc
소스 · gogs.dclub.kr/kim/freedoc