Aapastech 세션 백로그: 작업을 절대 잊지 않도록

Aapastech 세션 백로그: 작업을 절대 잃지 마세요

긴 세션과 멀티태스크 프롬프트는 AI 어시스턴트가 작업을 놓치게 만듭니다. 초반 요청은 사라지고 나중 턴이 한 세부 사항에 집중하게 됩니다. 이 스킬은 사용자 자신의 컴퓨터에 저장되는 백로그로 이 문제를 해결합니다. 대화 메모리는 진실의 원천이 아닙니다. 백로그가 진실의 원천입니다. 백로그에 없는 작업은 존재하지 않으며, 백로그에 있는 작업은 '完료' 또는 '폐기'로 표시되기 전까지 완료되지 않습니다.

이는 사용자 컴퓨터에서 셸 명령을 실행하거나 MCP 도구를 호출할 수 있는 모든 어시스턴트 또는 에이전트에서 작동합니다. 해당 컴퓨터의 모든 세션(어떤 도구나 모델에서든)은 동일한 백로그를 공유합니다.

개인정보 규칙: 작업 데이터는 작업을 실행하는 기기에 남습니다. 백로그를 클라우드 서비스, 호스팅 페이지, 커넥터 또는 공유 문서에 복사하지 마세요. 사용자 기기에 접근할 수 없는 경우 오프라인 모드(섹션 9)를 대신 사용하세요.

1. 백로그 찾기 및 엔진 실행하기

도구 목록에 backlog_* 도구가 있으면 (MCP 서버, 섹션 11) 해당 도구를 사용하세요. 이 도구들은 아래 명령어와 일대일로 매핑되며 폴더, 인코딩 및 업그레이드를 처리합니다. 이 섹션의 나머지는 건너뛰세요.

그렇지 않으면 백로그는 bl.py(엔진), config.json, tasks/(작업당 하나의 JSON 파일), sessions/, board.html 및 BOARD.md가 포함된 폴더입니다. 다음 순서로 찾으세요:

1. 사용자가 환경설정, 메모리 또는 프로젝트 지침에서 알려준 위치.
2. 설정된 경우 BACKLOG_DIR 환경 변수.
3. ~/Documents/Aapastech-Backlog (기본값).
4. ~/Documents/Claude-Backlog (v3 이전에 사용된 폴더 이름; 사용자의 작업이 그곳에 있으면 계속 사용).

실행하기. 이 문서에서 bl <command>는 약어입니다. 항상 전체 명령어를 입력하세요. 셸 변수에 저장하지 마십시오($BL …은 zsh(기본 macOS 셸)에서 실패합니다).

셸	명령어
macOS / Linux (bash, zsh)	python3 ~/Documents/Aapastech-Backlog/bl.py <command> …
Windows PowerShell	py -3 "$HOME\Documents\Aapastech-Backlog\bl.py" <command> … (py가 없으면 python 시도)
Windows cmd	py -3 "%USERPROFILE%\Documents\Aapastech-Backlog\bl.py" <command> …
Git Bash on Windows	py -3 ~/Documents/Aapastech-Backlog/bl.py <command> …

bl where는 사용 중인 폴더와 엔진 버전을 출력합니다. Windows에서 Documents는 종종 OneDrive(%USERPROFILE%\OneDrive\Documents)로 이동됩니다. ~\Documents가 없으면 그곳을 찾아보고, 모든 세션이 동일한 폴더를 찾도록 BACKLOG_DIR을 설정하도록 제안하세요.

Python. 엔진은 Python 3.8+와 그 외 다른 것은 필요로 하지 않습니다.

• macOS: 새 Mac에서 python3를 처음 호출하면 Apple의 "명령줄 개발자 도구 설치" 대화상자가 열릴 수 있습니다. 사용자에게 예상된 동작이며 수락해도 안전하다고 알리거나 python.org에서 Python을 설치하도록 안내하세요.
• Windows: Python은 일반적으로 설치되어 있지 않습니다. py -3 및 python이 모두 실패하면 사용자에게 python.org에서 "Add python.exe to PATH"를 체크하여 Python 3을 설치하거나 winget install Python.Python.3.12를 실행하도록 요청하세요. 다른 것으로 대체하지 마세요.

2. 기기에서 첫 실행 (부트스트랩)

아직 백로그가 없으면:

1. ~/Documents/Aapastech-Backlog 폴더(또는 사용자가 선택한 위치)를 생성합니다.
2. 이 스킬의 자체 폴더에서 scripts/bl.py를 그곳으로 복사합니다. 보드가 내장된 단일 stdlib 전용 Python 파일입니다.
3. 사용자에게 짧은 질문 하나를 합니다: 사용자를 기다리는 작업에 표시할 이름과 작업이 속하는 영역(3–8개 영역, 예: 클라이언트, 제품, 관리, 개인)은 무엇인지. 이미 알고 있는 내용에서 영역을 제안하세요. 그런 다음 실행합니다: bl init --owner "<이름>" --areas "영역1,영역2,…,개인,AI-Ops" 원하는 보드 이름이 있으면 --title "<보드 제목>"을 추가하세요(기본값 "Aapastech 백로그").
4. 보드 위치를 알려줍니다: file://…/Aapastech-Backlog/board.html. 열도록 제안하고(bl board --open), 탭을 고정하도록 권장하세요.
5. 스킬을 항상 켜두도록 제안하세요. 예를 들어 어시스턴트의 개인 환경설정 또는 지침 파일에: "모든 세션 시작 시와 작업이 있는 모든 작업 전에 세션 백로그 스킬을 항상 로드하세요."

업그레이드: bl version이 이 스킬의 scripts/bl.py(내부에서 VERSION = "…" 찾기)보다 낮은 버전을 출력하면 새 bl.py를 이전 파일 위에 복사하세요. 작업 데이터와 구성은 변경되지 않습니다.

3. 세션 식별 (세션당 한 번)

안정적인 세션 ID를 선택하고 모든 호출에서 재사용하세요:

• 플랫폼이 세션에 URL 또는 ID를 제공하면 이를 사용하고 URL을 --url로 전달하세요.
• 그렇지 않으면: <표면>-<YYYYMMDD-HHMM> 형식(세션 시작 시간 사용), 예: desktop-20261018-1652, code-20261018-0910, api-20261018-1200, sched-20261019-0600.

bl session --id <SID> --label "<표면> · <주제>" --surface code|desktop|cloud|api|scheduled [--url <링크>]

이 명령은 해당 세션의 열린 작업과 다른 곳에서 가져온 미할당 또는 부실 작업을 출력합니다. 연체되었거나 사용자 대기 중인 작업은 한 줄로 언급하세요. 전체 목록을 덤프하지 마세요.

4. 턴 루프 (작업이 있는 모든 턴)

A. 먼저 다시 읽기. 첫 번째 턴 이후 모든 턴 시작 시 bl open --session <SID>를 실행하세요. 특히 프롬프트가 하나의 하위 작업에 대한 심층 분석인 경우 이 단계를 수행하세요. 이 단계는 다른 작업이 잊혀지는 것을 방지합니다. 절대 건너뛰지 마세요.

B. 작업 전 캡처. 모든 새로운 요청은 작업을 시작하기 전에 한 배치로 캡처됩니다. "또한…", "상기시켜 줘…", "나중에…", "잊지 마…"와 같은 곁말도 포함됩니다. 배치를 파일 쓰기 도구로 JSON 파일에 쓴 다음 경로를 전달하세요. 파일은 모든 셸에서 작동합니다. echo를 통해 JSON을 파이핑하면 Windows 셸에서 깨지고 비ASCII 텍스트가 손상됩니다.

[
 {"title":"가격 페이지 재설계","area":"제품","eta":"1h","priority":"P1",
  "source":"프롬프트 16:52: 가격 페이지 재작업","next":"현재 카피 가져오기",
  "children":[{"title":"현재 카피 감사","eta":"10m"},
              {"title":"2가지 레이아웃 초안 작성","eta":"30m"},
              {"title":"선택된 레이아웃 게시","eta":"20m"}]},
 {"title":"공급업체에 답장","area":"관리","eta":"15m","status":"waiting_user","next":"사용자가 수량 확인"}
]

bl batch --session <SID> <path-to-file.json> (파일을 사용자의 프로젝트가 아닌 임시 공간에 두세요).

캡처를 한 줄로 요약하여 사용자가 수정할 수 있도록 하세요:

캡처됨: T-0042 가격 페이지 (1h) → T-0043 감사 (10m), T-0044 레이아웃 (30m), T-0045 게시 (20m); T-0046 공급업체 답장 (사용자 대기 중).

먼저 bl list를 확인하고, 중복을 생성하는 대신 기존 작업을 업데이트하세요. 하위 작업을 기존 작업 아래에 두려면 "parent":"T-0042" (또는 bl add에서 --parent T-0042)를 추가하세요.

C. 작업을 요구(Claim)한 다음 작업. 각 작업을 시작하기 전에 bl claim <ID> --session <SID> [--eta 20m]를 실행하세요. 다른 라이브 세션이 소유하고 있어 요구가 거부되면 그대로 두세요. 요구(Claim)는 잠겨 있으므로 두 세션이 동시에 하나를 획득할 수 없습니다. 가능하면 병렬로 작업하세요. 오케스트레이션 세션은 하위 에이전트를 위한 백로그를 업데이트하고 각 하위 에이전트에 작업 ID를 전달합니다.

D. 진행하면서 업데이트. bl update <ID> --session <SID> --log "결정/발견 사항" [--next "…"] [--output <경로 또는 링크>] [--status blocked|waiting_user|ready]

• 사용자의 결정을 사용자의 말 그대로 기록하세요.
• 생성한 모든 파일이나 링크는 --output에 넣으세요.
• 사용자를 기다리는 것은 --status waiting_user --next "<정확히 필요한 것>"을 의미합니다.

E. 정직하게 종료. 결과를 확인한 후에만 bl done <ID> --session <SID> --log "전달됨 …" --output …을 실행하세요. 하위 작업이 열려 있는 동안 상위 작업은 종료할 수 없습니다. 작업을 포기하려면 bl drop <ID> --session <SID> --reason "…"을 실행하세요. 절대 삭제하지 마세요.

F. 바닥글. 작업이 포함된 모든 응답은 bl footer --session <SID> [--exclude <방금 보고한 ID>]의 한 줄 출력으로 끝내세요.

5. 영역

모든 최상위 작업은 config.json에서 영역을 가져옵니다(bl areas에 목록 표시). 하위 작업은 상위 작업의 영역을 상속합니다. 가장 가까운 것을 선택하세요. 새로운 지속적인 작업 라인이 명확하게 나타날 때만 새 영역을 추가하고(bl areas --add "이름"), 추가할 때 언급하세요. bl areas --rename OLD NEW는 구성과 모든 작업에서 영역 이름을 바꿉니다.

6. ETA (모든 작업에 하나씩)

• ETA는 병렬 작업을 가정할 때 어시스턴트가 완료하는 데 걸리는 실제 시간입니다. 일반적으로 5–60분, 때로는 몇 시간, 드물게는 며칠입니다. 형식: 10m, 45m, 2h, 1h30m, 1d.
• 결과를 확인하는 시간을 포함하세요.
• 카운트다운은 요구(Claim) 또는 생성 시 시작됩니다. 보드는 연체된 작업을 빨간색으로 표시합니다.
• 예상 시간을 초과할 경우 즉시 재추정하세요: --eta 1h --eta-reason "…". 작업이 조용히 연체되도록 두지 마세요.
• waiting_user 작업의 경우 ETA는 사용자가 응답한 후 완료하는 시간입니다.

7. 교차 세션 규칙

• 요구(Claim)는 해당 세션이 작업을 계속 업데이트하는 동안 유효합니다. 24시간 동안 손대지 않으면 부실(stale) 상태가 되며, 모든 세션이 인수할 수 있습니다(인수는 기록됨).
• 사용자의 승인 없이 라이브 요구에 --force를 사용하지 마세요.
• 긴 작업이 끝나기 전에, 요구된 각 작업에 새 세션이 바로 작업할 수 있는 --next를 남기세요. 완료되지 않은 작업은 --status ready --log "해제됨: <상태>"로 해제하세요.
• "무엇이 열려 있나?", "어디까지 왔나?", "다른 세션이 무엇을 했나?"와 같은 질문에는 대화 메모리가 아닌 bl list(--all, --area X, --session Y)로 답하세요.
• 백로그는 하나의 기기에 속합니다. 다른 기기나 클라우드의 세션은 해당 기기에 대한 링크를 통해서만 사용합니다.
• 명령이 작업이 사용 중이라고 말하면 다른 세션이 그 순간에 쓰고 있는 것입니다. 잠시 후 한 번 다시 시도하세요.

8. 캡처를 건너뛰어야 하는 경우

동일한 응답에서 완전히 답변된 일회성 질문에 대해서만 캡처를 건너뛰세요. 그 외의 모든 것: 결과물이 있는 것, 둘 이상의 턴에 걸쳐 있는 것, 연기된 것은 모두 캡처하세요. 확실하지 않으면 캡처하세요.

9. 오프라인 모드 (사용자 기기에 접근 불가)

1. 작업을 플랫폼 자체 작업 목록(있는 경우) 또는 응답의 체크리스트(없는 경우)에 미러링하세요.
2. 각 의도된 bl.py 작업을 임시 공간(사용자 프로젝트 절대 안 됨)의 backlog-pending.jsonl에 한 줄에 하나의 JSON 객체로 대기열에 넣으세요: {"cmd":"add","args":{…},"at":"<iso>"}.
3. 사용자에게 한 번 알리세요: "컴퓨터에 접근할 수 없어 백로그 업데이트가 대기열에 추가되었으며, 다시 접속되면 동기화됩니다."
4. 매 턴마다 기기 연결을 다시 시도하세요. 연결되면 순서대로 대기열을 재생하고 bl open을 실행하세요.
5. 동기화 전에 세션이 종료되면 마지막 응답에 동기화되지 않은 작업 전체 목록을 포함해야 합니다.

10. 보드

board.html은 모든 쓰기 작업마다 재생성되며 30초마다 자동 새로고침됩니다. 다음을 표시합니다:

• 영역별 스윔레인, 열: 할 일 / 진행 중 / 차단됨 / <소유자> 대기 중 / 완료
• 각 카드의 ETA 및 카운트다운, 연체된 작업은 빨간색
• 각 작업을 생성, 작업, 완료한 세션
• 전체 로그 및 출력물로의 클릭스루

BOARD.md는 동일한 보드를 텍스트로 표시합니다.

사용자가 보기를 요청할 때 ("내 백로그 보여줘", "보드 열어줘", "무엇이 열려 있니?"):

• 백로그가 있는 컴퓨터에서 bl board --open을 실행하여 기본 브라우저에서 엽니다.
• 해당 컴퓨터의 브라우저에 접근할 수 없는 경우(예: 휴대폰 채팅), 연체 및 사용자 대기 중인 작업을 먼저, 영역별로 그룹화된 bl list의 짧은 요약을 붙여넣으세요.
• 보드는 로컬 파일입니다. 절대 게시, 업로드 또는 공유되지 않습니다.

11. 플랫폼 참고 사항

• MCP 클라이언트 (모든 어시스턴트 또는 에이전트 프레임워크). scripts/backlog_mcp.py는 stdio를 통해 backlog_session, backlog_open, backlog_add, backlog_claim, backlog_update, backlog_done, backlog_drop, backlog_list, backlog_show, backlog_footer, backlog_board, backlog_init 및 backlog_where를 노출하는 stdlib MCP 서버입니다. 명령어 python3(Windows py, 인수 -3 <path>) 및 인수 <path to backlog_mcp.py>로 등록하고, 선택적으로 env BACKLOG_DIR을 설정하세요. 동일한 bl.py를 실행하므로 셸 및 MCP 경로가 하나의 백로그를 공유합니다.
• API 기반 에이전트. API를 통해 호출되는 모델은 자체적으로 사용자 파일에 접근할 수 없습니다. 개발자는 백로그를 소유한 머신에서 MCP 서버(또는 자체 도구 뒤의 bl.py)를 실행하고 모델에 해당 도구를 제공합니다. 호스팅된 코드 샌드박스는 일시적이므로 거기에 백로그를 두면 샌드박스가 종료될 때 손실됩니다. 거기에 보관하지 마세요.
• 사용자 컴퓨터에 연결된 Claude 데스크톱/클라우드/휴대폰 세션 (기기 도구: device_bash, device_request_folder_access, device_commit_files; 지연된 경우 도구 검색을 통해 로드). 백로그 폴더 또는 그 상위 폴더(예: ~/Documents)는 연결된 폴더여야 합니다. 그렇지 않은 경우 device_request_folder_access를 한 번 호출하고 이유로 "이 컴퓨터에 작업 백로그를 유지하기 위해"를 제시하세요. 그런 다음 연결된 경로를 사용하여 device_bash를 통해 명령을 실행하세요(예: python3 $HOME/mnt/Documents/Aapastech-Backlog/bl.py …). 브리지를 통해 bl.py를 설치하려면 파일을 스테이징하고 기기에 커밋하세요(device_commit_files).
• Claude Code / Codex / Cursor / 기타 코딩 에이전트는 셸에서 직접 엔진을 실행합니다(섹션 1의 표 참조).

명령어 참조

bl init    [--owner 이름] [--areas "A,B,C"] [--title T]       첫 설정 / 소유자, 영역 또는 보드 제목 변경
bl version                                                    엔진 버전
bl where                                                      백로그 폴더, 엔진 버전, 보드 링크
bl areas   [--add 이름 …] [--rename OLD NEW]                  영역 나열 / 추가 / 이름 바꾸기
bl session --id SID --label L --surface S [--url U]           세션 등록; 열린 작업 출력
bl open    --session SID                                      이 세션의 열린 작업 + 미할당 작업
bl batch   --session SID file.json|-                          여러 개 추가(중첩된 "children" = 하위 작업)
bl add     --session SID --title T --area A --eta 20m [--parent ID] [--status S] [--next N] [--priority P1]
bl claim   ID --session SID [--eta 20m] [--force]
bl update  ID --session SID [--status S] [--eta E --eta-reason R] [--next N] [--log L] [--output O] [--area A] [--title T]
bl done    ID --session SID [--log L] [--output O] [--force]
bl drop    ID --session SID --reason R
bl list    [--all] [--area A] [--session SID] [--json]
bl show    ID
bl footer  --session SID [--exclude IDs]
bl board   [--open]

(번역을 위해 잘림)