D
Datronis
Kanban Studio›Markdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

개요

모든 Kanban 보드는 읽고, 쓰고, 복사하고 버전 제어가 가능한 일반 텍스트 Markdown 문서로 뒷받침됩니다. 문서에는 보드 데이터를 JSON으로 저장하는 기계 판독 가능 구조적 블록과 개인 메모를 위한 자유 형식 사용자 정의 블록이라는 두 가지 섹션이 있습니다.

스키마 v1JSON + 마크다운드라이런 안전
💡

항상 먼저 테스트 실행

적용을 클릭하기 전에 테스트 실행 버튼을 사용하여 편집 내용을 확인하세요. 백엔드는 보드를 수정하지 않고도 오류와 차이점 요약을 보고합니다.

문서 구조

전체 Kanban Markdown 문서는 세 부분으로 구성됩니다.

  • 사람이 읽을 수 있는 헤더(보드 제목, 생성 메모)
  • 구조화된 블록 — HTML 주석 표시자 사이의 JSON 데이터
  • 사용자 정의 블록 — 무료 마크다운(메모, 인어 다이어그램, 링크)
board.md
# My Project Board

Generated by Kanban Markdown schema v1.

<!-- KANBAN:STRUCTURED:START -->
```kanban-structured
{
  "version": 1,
  "board": {
    "id": "board-abc123",
    "title": "My Project Board"
  },
  "columns": [
    { "id": "col-1", "title": "Backlog",     "color": "#64748b", "order": 0 },
    { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
    { "id": "col-3", "title": "Done",        "color": "#10b981", "order": 2 }
  ],
  "tasks": [
    {
      "id": "task-1",
      "columnId": "col-2",
      "position": 0,
      "title": "Build authentication flow",
      "description": "Implement JWT login, register, and token refresh.",
      "priority": "high",
      "tags": ["backend", "security"],
      "assigneeIds": ["member-uuid-1"],
      "mentionMemberIds": ["member-uuid-2"],
      "estimatePoints": 5,
      "dueDate": "2025-03-15",
      "plannedStartAt": "2025-03-10",
      "plannedEndAt": "2025-03-15",
      "timeboxMinutes": 90,
      "isCompleted": false,
      "archivedAt": null,
      "checklist": [
        { "title": "Design DB schema",   "isDone": true  },
        { "title": "Write unit tests",   "isDone": false },
        { "title": "Deploy to staging",  "isDone": false }
      ]
    }
  ]
}
```
<!-- KANBAN:STRUCTURED:END -->

<!-- KANBAN:CUSTOM:START -->
## Team Notes

- Sprint ends Friday
- Backend review at 3 PM

```mermaid
flowchart LR
  A[Backlog] --> B[In Progress] --> C[Done]
```
<!-- KANBAN:CUSTOM:END -->
모든 섹션에 주석이 달린 완전한 보드 문서
⚠️

주석 표시를 제거하지 마십시오

<!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> 및 <!-- KANBAN:CUSTOM:END --> 마커가 필요합니다. 이를 제거하면 구문 분석 오류가 발생합니다.

열

열은 보드의 워크플로 단계를 정의합니다. order 값에 따라 왼쪽에서 오른쪽으로 렌더링됩니다.

JSON
"columns": [
  { "id": "col-1", "title": "To Do",       "color": "#64748b", "order": 0 },
  { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
  { "id": "col-3", "title": "Review",      "color": "#f59e0b", "order": 2 },
  { "id": "col-4", "title": "Done",        "color": "#10b981", "order": 3 }
]
예: 서로 다른 색상이 있는 4개의 열
FieldTypeRequiredDescription
idstringYes고유 열 식별자(UUID 또는 안정적인 슬러그)
titlestringYes보드에 표시된 열 제목
colorstringYes열 강조 색상(16진수)입니다. 카드의 왼쪽 테두리로 표시됨
orderintegerYes0부터 시작하는 표시 순서(오름차순, 왼쪽에서 오른쪽)
ℹ️

Note

열 ID는 보드 내에서 고유해야 합니다. 작업은 이 id로 열을 참조합니다.

작업

태스크는 작업의 핵심 단위입니다. 각 작업은 (columnId을 통해) 열 내부에 있으며 해당 열 내에서 position별로 정렬됩니다.

최소한의 작업

JSON
{
  "id": "task-abc",
  "columnId": "col-1",
  "position": 0,
  "title": "Write release notes",
  "description": "",
  "priority": "medium",
  "tags": [],
  "assigneeIds": [],
  "mentionMemberIds": [],
  "estimatePoints": null,
  "dueDate": null,
  "plannedStartAt": null,
  "plannedEndAt": null,
  "timeboxMinutes": null,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": []
}
필수 필드만 채워짐 — 모든 선택 필드는 null이거나 비어 있습니다.

모든 필드가 포함된 전체 작업

JSON
{
  "id": "task-xyz",
  "columnId": "col-2",
  "position": 0,
  "title": "Redesign checkout page",
  "description": "Full UX overhaul based on user research findings.",
  "priority": "critical",
  "tags": ["ux", "frontend", "q1-goal"],
  "assigneeIds": ["member-alice", "member-bob"],
  "mentionMemberIds": ["member-pm"],
  "estimatePoints": 8,
  "dueDate": "2025-04-01",
  "plannedStartAt": "2025-03-20",
  "plannedEndAt": "2025-04-01",
  "timeboxMinutes": 120,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": [
    { "title": "User interviews",       "isDone": true  },
    { "title": "Wireframes approved",   "isDone": true  },
    { "title": "Implement components",  "isDone": false },
    { "title": "A/B test live",         "isDone": false }
  ]
}
우선순위, 태그, 담당자, 체크리스트, 시간 추적이 포함된 생산 사례
FieldTypeRequiredDescription
idstringYes고유 작업 식별자(UUID 또는 안정적인 슬러그)
columnIdstringYes이 작업이 속한 열의 ID
positionintegerYes열 내 0부터 시작하는 정렬 순서
titlestringYes작업 제목(1~280자)
descriptionstringNo마크다운 호환 자세한 설명
priorityenum
"low""medium""high""critical"
No작업 긴급도 수준
tagsstring[]No필터링 및 그룹화를 위한 자유 형식 레이블 문자열
assigneeIdsstring[]No이 작업에 할당된 사람들의 구성원 ID
mentionMemberIdsstring[]No본 업무에 언급(통지)된 회원ID
estimatePointsinteger|nullNo스토리 포인트 추정(피보나치: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoISO 8601 날짜 문자열: YYYY-MM-DD
plannedStartAtstring|nullNoISO 8601 날짜/시간: 계획된 시작
plannedEndAtstring|nullNoISO 8601 날짜/시간: 종료 예정
timeboxMinutesinteger|nullNo타임박싱을 위한 포커스 세션 길이
isCompletedbooleanNo작업을 완료로 표시합니다(UI에 취소선 추가).
archivedAtstring|nullNo작업이 보관된 ISO 8601 날짜/시간입니다. 보관된 작업은 보드에서 숨겨집니다.
checklistobject[]No하위 작업 체크리스트 항목(체크리스트 섹션 참조)

체크리스트 항목

각 작업은 별도의 작업을 만들지 않고도 개별적으로 완료로 표시할 수 있는 간단한 하위 작업인 체크리스트 항목의 단순 목록을 지원합니다.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
세 가지 체크리스트 항목: 첫 번째 항목 완료, 나머지 두 항목
FieldTypeRequiredDescription
titlestringYes체크리스트 항목 라벨(1~255자)
isDonebooleanYes이 항목이 체크되어 있는지 여부

사용자 정의 메모 섹션

<!-- KANBAN:CUSTOM:START -->와 <!-- KANBAN:CUSTOM:END --> 사이의 모든 것이 스크래치패드입니다. 전체 Markdown 및 Mermaid 다이어그램을 지원합니다. 콘텐츠는 보드 엔진에 의해 파싱되지 않습니다. 미리보기 탭에만 표시됩니다.

Markdown
<!-- KANBAN:CUSTOM:START -->
## Sprint Notes

- Daily standup at 10:00 AM
- Backend API freeze on Friday

```mermaid
gantt
  title Sprint 12
  section Tasks
  Auth flow     :done, 2025-03-10, 3d
  Dashboard UI  :active, 2025-03-13, 4d
  API docs      :2025-03-17, 2d
```

> Reminder: update JIRA tickets before end of day.
<!-- KANBAN:CUSTOM:END -->
인어 간트 차트가 있는 노트
💡

Tip

스프린트 노트, 팀 링크, 간트 차트, 아키텍처 다이어그램 등 보드 데이터와 함께 표시하려는 모든 항목에 대해 사용자 정의 섹션을 사용하세요.

우선순위 가치

priority 필드는 네 가지 값 중 정확히 하나를 허용합니다. 각각은 UI의 고유한 배지 색상에 매핑됩니다.

FieldTypeRequiredDescription
lowenum valueNo긴급성이 낮습니다. 슬레이트/회색으로 표시됩니다.
mediumenum valueNo기본값. 호박색/노란색으로 표시됩니다. 우선순위 생략의 기본값은 이것입니다.
highenum valueNo중요합니다. 주황색으로 표시됩니다.
criticalenum valueNo차단. 빨간색/장미색으로 표시됩니다.

보관 작업

작업을 보관하려면 해당 archivedAt 필드를 ISO 날짜/시간 문자열로 설정하세요. 보관된 작업은 활성 보드 보기에서 제외되지만 기록에는 보존됩니다.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
보관된 작업 — 보드에서 숨겨지고 스냅샷에 보존됨
ℹ️

Note

archivedAt를 null로 설정하면 작업 보관이 취소됩니다. 보드에서 현재 활성화된 작업을 보관하는 마크다운 스냅샷을 적용할 때 diff 요약에는TasksToArchive가 표시됩니다.

드라이런 및 진단

테스트 실행 기능은 변경 사항을 적용하지 않고 가격 인하를 검증합니다. 백엔드는 diffSummary(변경 사항) 및 오류나 경고를 나열하는 diagnostics 배열을 반환합니다.

성공적인 테스트 실행 응답

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: true는 마크다운이 유효하고 적용하기에 안전하다는 것을 의미합니다.

오류가 있는 테스트 실행

JSON
{
  "ok": false,
  "dryRun": true,
  "diagnostics": [
    {
      "code": "unknown_column_id",
      "message": "Task 'task-xyz' references unknown column 'col-999'.",
      "line": 42,
      "severity": "error"
    },
    {
      "code": "duplicate_task_id",
      "message": "Task ID 'task-abc' is used more than once.",
      "line": 67,
      "severity": "error"
    }
  ],
  "diffSummary": {
    "columnsCreated": 0,
    "columnsTouched": 0,
    "tasksCreated": 0,
    "tasksTouched": 0,
    "tasksToArchive": 0
  }
}
ok: false — 적용하기 전에 오류를 수정하세요.
FieldTypeRequiredDescription
codestringYes기계가 읽을 수 있는 오류 코드(예:known_column_id)
messagestringYes사람이 읽을 수 있는 문제 설명
lineintegerYes마크다운 문서의 대략적인 줄 번호
severityenum
"error""warning"
Yes'오류'(차단 적용) 또는 '경고'(적용 진행)
🚫

오류 차단 적용

진단에 '오류' 심각도의 항목이 포함된 경우 적용 작업 진행이 거부됩니다. 경고는 권고 사항이므로 차단하지 마세요.

권장되는 작업 흐름

Markdown을 통해 보드를 편집할 때 다음 흐름을 따르세요.

  • 보드에서 Markdown 패널을 엽니다.
  • 구조화된 블록에서 JSON 편집 — 열 또는 작업 추가/수정
  • 아무것도 변경하지 않고 검증하려면 시험 실행을 클릭하세요.
  • 진단 목록에 표시된 오류를 수정하세요.
  • 라이브 보드에 변경 사항을 적용하려면 적용을 클릭하세요.
  • 다운로드를 사용하여 로컬 .md 백업을 저장하세요.
💡

버전 관리 팁

문서는 일반 텍스트이므로 Git 저장소에 붙여넣고, 버전을 비교하고, 이전 스냅샷을 다시 적용하여 이전 보드 상태를 복원할 수 있습니다.

Schema v1 · Updated September 2026