Kanban 보기 상세

Kanban은 Markdown의 H2 section과 top-level list를 작업 보드로 투영한다. 별도 보드 데이터베이스가 원본이 되는 방식이 아니다. 카드를 옮기거나 편집하면 지원되는 범위의 Markdown이 바뀌고, 검색·필터·density처럼 읽기 위한 상태는 원문과 분리된다.

이 장은 다음 질문에 답한다.

• 어떤 Markdown이 완전히 편집 가능한 보드가 되는가?
• 카드와 컬럼을 드래그하면 원문의 어느 범위가 이동하는가?
• 검색이나 필터가 켜졌을 때 이동이 잠기는 이유는 무엇인가?
• WIP, 담당자, 우선순위, 날짜와 라벨은 어디에 저장되는가?
• Desktop 표현 설정과 Hugo 결과는 어디까지 이어지는가?

1. 가장 빠른 시작

1. Kanban Lab의 01_release-board.md를 내려받거나 Binder에 복사한다.
2. Source에서 H2와 task 줄이 보이는지 확인한다.
3. 작성 영역의 보기 선택기에서 Kanban을 선택한다.
4. 홈페이지 소개 문구 확정 카드의 drag handle을 진행 중 컬럼으로 끈다.
5. Source로 돌아와 카드 줄과 들여쓴 본문이 함께 이동했는지 확인한다.

영상은 Source → Kanban 전환, 검색·필터, 필터 해제, 실제 카드 drag/drop과 Source 재확인을 한 흐름으로 보여 준다. 포인터와 하단 캡션은 클릭·드래그 대상과 결과를 설명한다.

2. 원본 권위와 상태 경계

Kanban에서 다루는 상태는 세 층으로 나뉜다.

따라서 카드 이동 성공은 화면 좌표가 달라진 것으로 끝나지 않는다. 대상 Markdown section 아래로 카드의 source range가 실제 이동하고 저장되어야 한다. 반대로 검색 결과를 좁히거나 완료 카드를 숨겨도 원문의 카드가 삭제되어서는 안 된다.

3. 편집 가능한 strict 문법

완전히 편집 가능한 보드는 다음 순서를 따른다.

---
title: 릴리즈 보드
---

# 릴리즈 보드

## 백로그 [wip:4]

- [ ] 소개 문구 확정 [owner:민지] [priority:P0] [label:홈페이지]
  - 핵심 문장과 보조 문장을 함께 검토한다.

## 진행 중 [wip:3]

- [ ] 기능 영상 캡처 [owner:준] [due:2026-08-05]

## 완료

- [x] 예제 Binder 준비

## Archived

- [x] 초기 스파이크

strict 보드의 규칙은 다음과 같다.

• 선택적인 front matter 다음에 H1 제목을 한 번 둘 수 있다.
• 컬럼은 H2로 시작한다.
• 카드는 H2 바로 아래의 top-level list 또는 task item이다.
• 카드의 들여쓴 연속 줄은 같은 카드의 상세 내용이다.
• Archived 컬럼이 있다면 마지막 H2여야 한다.
• H2 사이의 독립 문단, H3 heading, 들여쓰지 않은 일반 텍스트는 strict 편집 범위를 깨뜨린다.

Glif는 strict 문서를 sourceEditable: true로 해석한다. 추가·편집·이동·삭제 같은 명령은 현재 source revision과 대상 range를 확인한 뒤 Markdown을 변경한다.

4. H2는 컬럼이다

다음 H2가 나오기 전까지의 source range가 하나의 컬럼이다.

## 진행 중 [wip:3]

화면에는 진행 중만 제목으로 보이고 [wip:3]은 WIP badge와 경고 계산에 사용된다. 컬럼 제목을 바꾸면 H2 text가 바뀌고, 컬럼을 이동하면 heading과 그 아래 카드 범위가 함께 이동한다.

지원 동작은 다음과 같다.

• 컬럼 추가
• 컬럼 제목과 WIP 제한 편집
• drag handle 또는 명시적 이동 action으로 컬럼 재정렬
• 빈 컬럼 삭제
• 카드가 있는 컬럼 삭제 시 확인 후 source range 삭제

Archived는 정확히 이 영문 제목일 때 보관 컬럼으로 인식된다. 번역된 표시 문자열이나 임의의 archive metadata를 숨은 상태로 만들지 않는다.

5. list와 task는 카드다

일반 list는 상태 marker가 없는 카드다.

- 회의 안건 정리

task marker를 쓰면 완료 상태가 Markdown에 남는다.

- [ ] 진행할 카드
- [x] 완료한 카드

카드의 들여쓴 줄은 카드와 함께 움직이는 상세 범위다.

- [ ] Kanban 영상 만들기 [owner:준]
  - Source 전환을 포함한다.
  - drag 결과를 다시 Source에서 확인한다.

카드 제목·상세·task marker를 편집하거나 카드를 추가·삭제·archive하면 대응하는 list range가 바뀐다. 카드의 메뉴에서 원문에서 보기를 선택하면 해당 줄로 돌아갈 수 있다.

6. 카드 metadata suffix

카드 제목 끝에 연속된 suffix를 붙이면 badge와 편집 필드로 읽힌다.

- [ ] 공개 가이드 교정 [owner:민지] [priority:P1] [due:2026-08-08] [stale:2026-08-01] [label:가이드] [label:QA]

suffix는 제목 끝에서부터 연속해서 해석한다. 제목 중간의 [owner:민지]나 잘못된 날짜는 metadata로 확정하지 않는다. 카드 편집기는 제목과 상세 본문을 metadata 필드와 분리해서 보여 주지만 저장 결과는 다시 이 Markdown suffix다.

7. WIP 제한 읽기

컬럼 제목 끝의 [wip:N]에서 N은 1 이상의 정수다.

## 진행 중 [wip:2]

WIP badge는 현재 카드 수와 제한을 함께 보여 준다. 카드 수가 제한을 넘으면 컬럼과 badge가 초과 상태를 드러낸다. 이 신호는 숨은 서버 정책이 아니라 원문에 적힌 작업 규칙이다.

현재 보드가 표시하는 WIP 경고와 source의 숫자가 다르면 Source를 먼저 확인한다. 빈 값, 0, 음수와 정수가 아닌 값은 유효한 제한으로 취급하지 않는다.

8. 카드 drag/drop

카드 drag handle을 잡으면 Glif는 카드의 source range와 현재 컬럼을 기억한다. 다른 컬럼이나 카드 사이의 drop target으로 이동하면 placeholder가 실제 삽입 위치를 보여 준다.

1. 이동할 카드의 drag handle에 pointer를 둔다.
2. pointer를 누른 채 대상 컬럼으로 이동한다.
3. 표시된 drop placeholder가 원하는 위치인지 확인한다.
4. pointer를 놓는다.
5. 저장이 끝나면 Source에서 이동한 list range를 확인한다.

drag와 명시적 이동 action은 같은 source-backed 명령 경계를 사용한다. 저장 실패나 stale revision을 성공처럼 보이지 않으며, 원문이 바뀌지 않았다면 이동도 완료된 것으로 보지 않는다.

9. 컬럼 drag/drop

컬럼 제목의 drag handle은 H2 section 전체를 옮긴다. 카드 한 장이 아니라 컬럼 heading부터 다음 H2 직전까지가 이동 단위다.

• Archived는 마지막 컬럼이라는 문법 경계를 유지해야 한다.
• filter 때문에 컬럼의 일부 카드가 숨은 상태에서는 source order를 오판하지 않도록 이동이 제한될 수 있다.
• 키보드 사용자는 컬럼 action menu의 위·아래 이동을 사용한다.

컬럼을 옮긴 뒤에는 Source의 H2 순서와 Kanban의 왼쪽→오른쪽 순서가 같은지 확인한다.

10. 검색과 보기 필터

보드 상단 검색은 카드 제목·상세·metadata와 컬럼 제목을 좁혀 본다. 검색어는 카드를 삭제하거나 publish 대상에서 제외하지 않는다.

지원되는 보기 필터는 다음과 같다.

• 완료 숨김: checked task를 화면에서 숨긴다.
• 아카이브 숨김: Archived 컬럼을 화면에서 숨긴다.
• 필터 해제: 검색어와 보기 필터를 한 번에 초기화한다.

필터 중 이동이 잠기는 이유

화면에 보이는 카드 사이에 source sibling이 숨겨져 있으면, 시각적 순서만으로 정확한 삽입 위치를 결정할 수 없다. 이때 Glif는 필터 적용 중임을 알리고 재정렬을 잠근다.

이것은 기능 누락이 아니라 데이터 보존 장치다. 검색어와 필터를 해제하고 모든 source sibling이 보이는 상태에서 이동한다. 필터된 화면 순서를 원문 순서로 오인해 숨은 카드를 덮어쓰지 않는다.

11. 카드·컬럼 편집 흐름

카드 추가

각 컬럼의 추가 control에서 제목을 입력한다. task 카드가 필요한 경우 task marker를 선택하고, 상세·담당자·우선순위·날짜·라벨을 채운다. 저장 후 H2 아래에 새 top-level list range가 생긴다.

카드 편집

카드 제목이나 편집 action을 열어 다음을 바꾼다.

• 제목
• 상세 본문
• task 완료 상태
• 담당자
• P0~P3 우선순위
• due/stale 날짜
• 하나 이상의 label

archive와 delete

archive는 카드 range를 마지막 Archived H2 아래로 옮긴다. Archived 컬럼이 없으면 지원되는 명령이 컬럼을 준비한 뒤 이동한다. delete는 source range를 제거하는 파괴적 동작이므로 확인 문구와 현재 문서를 확인한다.

undo와 복구

이동이나 편집 직후 일반 undo로 되돌릴 수 있다. 예상과 다른 결과가 보이면 다음 편집을 이어가기 전에 Source로 전환해 현재 Markdown을 확인한다.

12. best-effort 읽기 경계

기존 문서가 strict 문법이 아니어도 H2와 H3 구조가 있으면 Kanban은 가능한 범위에서 읽기 보드를 만든다.

H3 카드 예제는 H3와 이어지는 문단을 카드처럼 보여 준다. 이 경우 model은 best-effort이고 sourceEditable: false다.

best-effort 화면이 보인다고 H3 문서를 task list로 자동 변환하지 않는다. 편집 가능한 보드가 필요하면 Source에서 각 카드를 top-level list 또는 task로 명시적으로 정리한다.

13. 표현 설정과 projection profile

Kanban 정보 pane에서는 내용과 분리된 표현을 조정한다.

• density: 넓게, 기본, 컴팩트
• 카드 style: 조용, 틴트, 채움, 선
• radius: 각짐, 부드러움, 둥글
• accent palette와 컬럼 accent
• 제목 위치·정렬·강조
• 기본 보기 filter

이 값은 Markdown 카드의 내용이 아니라 문서별 projection profile의 features.kanban.projection에 저장된다. profile은 renderer-neutral 표현 intent를 담고, 검색어·현재 선택 카드·pointer 위치·drag placeholder 같은 세션 상태는 저장하지 않는다.

14. 키보드와 접근성

• Tab과 Shift+Tab으로 검색, 카드 action, drag 대안과 정보 pane control을 이동한다.
• Enter 또는 Space로 button과 menu를 연다.
• drag가 어려우면 카드·컬럼 action menu의 명시적 이동을 사용한다.
• 검색 또는 필터로 이동이 잠기면 안내를 읽고 필터 해제를 실행한다.
• 원문 확인 action은 현재 카드의 source line으로 돌아간다.

색만으로 WIP 초과, 완료, overdue와 stale을 구분하지 않는다. badge text와 접근 가능한 이름을 함께 사용한다.

15. Desktop와 Hugo 결과

Desktop Kanban은 읽기와 source-backed 편집을 위한 작업 표면이다. Hugo는 저장된 Markdown과 지원 profile을 materialize한 읽기 표면이다.

Desktop과 Hugo가 픽셀 단위로 같다고 주장하지 않는다. 구조, 읽을 수 있는 metadata와 지원되는 표현 intent를 이어가되 Desktop의 편집 control이나 임시 필터 상태는 게시하지 않는다.

16. 실증 예제 구성

캡처는 배포 fixture의 복사본에서 실행한다. 따라서 영상 속 drag/drop은 실제 Markdown을 바꾸지만, 다운로드하는 예제는 항상 초기 상태다.

17. 문제 해결

18. 검증 체크리스트

• H2 수와 화면 컬럼 수가 같다.
• top-level 카드와 화면 카드 수가 같다.
• WIP와 metadata가 source suffix와 같다.
• 검색·필터만 사용할 때 source hash가 바뀌지 않는다.
• drag/drop 뒤 대상 카드 range만 의도한 H2 아래로 이동한다.
• 들여쓴 카드 상세도 함께 이동한다.
• 필터 중 안전하지 않은 재정렬이 잠긴다.
• Source로 돌아가 실제 변경을 읽을 수 있다.
• Hugo에서 구조와 metadata가 읽히고 Desktop 편집 control은 노출되지 않는다.
• 데스크톱·모바일 가이드 페이지에서 이미지와 영상이 로드되고 가로 overflow가 없다.

기능 근거

• ED-01: Markdown 작성·저장과 source authority
• ED-22: 구조화된 Kanban 보기와 source-backed 작업 흐름
• ED-23: 같은 문서 identity를 유지하는 보기 전환과 projection profile
• PB-01: 저장된 Markdown을 Hugo 결과로 materialize

단계별 실습은 같은 Markdown을 Kanban으로 활용하기에서 이어진다.