tk-ai

PRD(제품 요구사항 문서)를 개별 마크다운 태스크 파일로 변환하는 AI 기반 검증 및 보정 기능을 갖춘 태스크 관리 CLI입니다.

개요

tk-ai는 AI 기반 태스크 추출 시스템입니다. 자유로운 형식의 PRD를 처리할 수 있습니다:

• PRD 전체를 AI가 분석하여 태스크 추출 (Claude Code CLI 활용)
• 효율적인 증분 업데이트를 위한 콘텐츠 해싱
• 추가적인 메타데이터 보정을 위한 AI 보정
• 모든 AI 제안에 대한 HITL(Human-in-the-loop) 승인

주요 기능

• 증분 업데이트: 콘텐츠/메타 해싱을 사용해 수정된 태스크만 변경
• 캐시 친화적: 빠른 작업을 위한 .cache/tasks.index.json 유지
• 마크다운 SSOT: 각 태스크는 YAML 프론트 매터가 있는 별도의 .md 파일
• AI 보정: MCP(Model Context Protocol)를 활용한 메타데이터 보정
• 검증: 스키마 검증, 중복 감지, 상태 정규화

설치

npm install -g tk-ai

명령어

PRD에서 태스크 추출

tk-ai make-tasks <prd.md> [옵션]

• --out-dir <디렉토리>: 출력 디렉토리 (기본값: tasks/)
• --dry-run: 쓰기 없이 변경 사항 미리보기
• --update-mode merge|overwrite: merge는 사람의 편집 내용 보존 (기본값: merge)
• --include-done: 완료/취소된 태스크도 업데이트에 포함

추출 규칙:

1. 마크다운 체크박스 (- [ ], - [x]) → 각각 하나의 태스크
2. 체크박스 없음 → 헤더 아래 1차 불릿 → 각각 하나의 태스크
3. 소스 위치를 source_anchor로 보존
4. PRD 발췌 3-5줄을 인용문으로 포함

태스크 파일 검증

tk-ai validate-tasks [--dir tasks] [--json]

• 필수 필드 확인 (id, title, status, source_prd 등)
• 상태 값과 날짜 형식 검증
• 중복 ID 감지
• 오류(중요)와 경고(권장) 보고

AI 기반 보정

tk-ai correct-tasks [--dir tasks] [--suggest-only | --autofill]

• --suggest-only: 검토를 위한 JSON 제안 출력
• --autofill: 승인 후 보정 적용
• 누락된 제목/설명 채우기
• 우선순위(1-5)와 라벨 제안
• 상태 철자 정규화 (예: cancelled → canceled)

캐싱을 통한 태스크 목록

tk-ai list-tasks [--filter <쿼리>] [--refresh]

• 빠른 목록을 위한 캐시 인덱스 사용
• --refresh: 파일에서 캐시 재구축
• 기본 정렬: 활성 태스크 우선 → 우선순위 내림차순 → 생성일 오름차순

파일 구조

/tasks/
  0--login-otp.md
  1--rate-limit.md
.cache/
  tasks.index.json
PRD.md

태스크 파일 스키마

---
id: "0"
title: 이메일 + OTP 로그인 구현
status: todo  # todo|in_progress|review|done|blocked|canceled
priority: 4   # 1-5 스케일
labels: [auth, api]
sourcePrd: ./PRD.md
sourceAnchor: auth#L12-L18
createdAt: 2025-08-10T00:00:00Z
contentHash: "sha1:ab12..."  # title + description + body
metaHash: "sha1:cd34..."     # priority + status + labels + deps
schema: v0
# 선택 필드
description: "이메일+OTP 로그인 플로우와 토큰 리프레시"
deps: []
assignees: []
due:
---
> PRD 발췌 (3-5줄)
> 원본 요구사항 컨텍스트

증분 업데이트 알고리즘

1. PRD 파싱 → 후보 추출 → incremental ID 생성 (0, 1, 2...)
2. 기존 파일의 경우:
   • contentHash 비교 → 변경 없으면 건너뛰기
   • 모드에 따라 병합/덮어쓰기 적용
3. 새 태스크의 경우:
   • 파일 생성 (매칭되는 done/canceled는 건너뛰기)
4. 파일/콘텐츠/메타 해시로 캐시 업데이트
5. 목록 작업은 캐시 사용, 파일 변경 시 재검증

AI 통합

tk-ai는 MCP(Model Context Protocol)를 활용하여 Claude Code CLI로 보정합니다:

시스템 프롬프트

• 역할: 태스크 메타데이터 보정자 (MCP 도구 활용)
• 출력: 스키마와 일치하는 JSON만
• 제약: 1-2문장 설명, 명령형 제목
• 수정 금지: id, sourcePrd, sourceAnchor, done/canceled 상태

보정 필드

• title: 명령형, 80자 미만
• description: 1-2문장, 구체적
• priority: 1-5 스케일 (5 = 최고)
• labels: 도메인 용어 (auth, frontend, api 등)

워크플로우 예시

# 1. PRD에서 태스크 추출
tk-ai make-tasks PRD.md

# 2. 추출 검증
tk-ai validate-tasks

# 3. AI 보정 미리보기
tk-ai correct-tasks --suggest-only

# 4. 보정 적용
tk-ai correct-tasks --autofill

# 5. 활성 태스크 목록
tk-ai list-tasks

설계 원칙

1. 결정적 우선: 예측 가능한 추출, AI는 향상만을 위해
2. 사람 제어: 모든 AI 제안은 승인 필요
3. 파일 기반 SSOT: 각 태스크 = 하나의 파일, Git 친화적
4. 해시 기반 효율성: 변경된 콘텐츠만 처리
5. 사람 편집 보존: 병합 모드는 수동 변경 사항 존중

의존성

• meow: CLI 프레임워크
• remark/mdast: 마크다운 파싱
• gray-matter: 프론트 매터 파싱
• crypto: SHA1 해싱
• zod: 스키마 검증
• chalk: 터미널 색상 출력

라이선스

MIT