Quick Start

lee-spec-kit은 PRD, idea, feature 문서를 만들고, 에이전트가 그 문서를 기준으로 작업하도록 돕는 도구입니다.

npx lee-spec-kit init
npx lee-spec-kit integrations codex-hooks
npx lee-spec-kit idea improve-auth-flow
npx lee-spec-kit feature user-auth --issue 123 # GitHub: select an existing Issue
# Local: npx lee-spec-kit feature user-auth

init은 GitHub/Local 워크플로우와 Task 구현 위임, Plan/Task/Feature 검수, Local 통합 방식을 대화형으로 설정합니다. 자동화 환경에서는 같은 값을 플래그로 지정할 수 있습니다.

npx lee-spec-kit init --workflow local --task-agent on --reviews plan,feature --completion-strategy local-squash --non-interactive

그 다음부터는 자연어로 요청하면 됩니다.

왜 만들었나

이 CLI는 AI 에이전트와 함께 프로젝트를 진행할 때, 문서와 실제 작업 흐름이 따로 놀지 않게 하려고 만들었습니다.

단순히 문서 폴더만 만드는 것이 아니라, 에이전트가 지금 어떤 feature를 보고 있는지, 다음에 무엇을 해야 하는지, 어디서 사용자 확인이 필요한지를 같은 규칙 안에서 다루도록 만드는 쪽에 더 가깝습니다.

작업 구조는 SDD(spec-driven development) 기반의 PRD → idea → feature 흐름을 따릅니다. PRD는 docs/prd/에서 상위 요구사항을 정리하는 공간이고, idea는 후보나 실험을 적어두는 단계이며, feature는 실제로 실행할 단위를 spec.md, plan.md, tasks.md, decisions.md로 내려 관리하는 단계입니다.

구조적으로는 spec-kit과 OpenSpec의 접근을 참고했습니다.

사람은 보통 이렇게 요청합니다

• "이 요구사항 기준으로 idea 정리해줘."
• "이 idea를 feature로 올려서 진행해줘."
• "현재 feature 기준으로 issue 초안 만들어줘."
• "규칙에 따라 다음 feature 진행해줘."
• "작업 끝났으니 문서랑 같이 점검해줘."

주요 명령

• init: docs/workflow 구조 초기화
• idea: 구현 전 idea 문서 생성
• feature: 실제 작업 단위 생성
• task add: tasks.md에 문서 전용 task block 추가
• decision add: decisions.md에 문서 전용 ADR block 추가
• docs: 내장 agent policy 문서 조회
• detect: 현재 워크스페이스가 lee-spec-kit 프로젝트인지 감지
• github: issue/pr 본문 생성 및 검증
• integrations codex-hooks: 현재 workspace와 configured project root용 Codex hooks 생성/제거
• integrations codex: 선택적 전역 [features].hooks 설정 설치/제거
• commit-audit --json: hooks용 commit-time docs path + canonical commit subject validator
• workflow-audit --json: hooks용 docs sync validator
• knowledge ci: 독립 OpenWiki 예약/수동 CI scaffold 생성
• knowledge migrate [--apply] --json: 기존 Feature의 문서 영향 판정 도입 상태를 dry-run하고, 안전한 대상만 명시적으로 grandfather 처리
• local verify <feature-ref> --json: local Feature worktree에서 검사를 실행하고 결과를 정확한 tip/tree에 결속
• local merge <feature-ref> --json: 검증된 local Feature를 설정된 fast-forward 또는 squash 전략으로 base branch에 통합
• local cleanup <feature-ref> --json: managed worktree 제거 및 설정에 따른 통합 완료 Feature 브랜치 삭제

지원 모드:

• embedded: 프로젝트 안에 docs/를 함께 둡니다.
• standalone: workspace root 아래에서 docs repo와 project repo를 따로 관리합니다.

실험적 OpenWiki Knowledge 계층은 단일 플래그로 활성화합니다.

npx lee-spec-kit config --openwiki true
npx lee-spec-kit knowledge ci --json

knowledge ci는 프로젝트 저장소에 .github/workflows/lee-spec-kit-knowledge.yml을 생성합니다. 생성된 workflow는 OpenWiki 0.5.2를 직접 실행하고 openwiki/, AGENTS.md, CLAUDE.md 변경을 검토용 PR에 올립니다. 실패하면 완료된 페이지만 draft PR에 보존해 다음 예약 실행의 입력 baseline으로 사용합니다. 원문 실행 문맥이 들어갈 수 있는 .run.json은 원격 브랜치와 PR에 올리지 않습니다. 성공한 최신 소스 결과만 review-ready 상태로 전환합니다. lee-spec-kit은 OpenWiki 프로세스, 페이지 큐, 재시도, 검증 결과, receipt 또는 실행 상태를 해석하거나 제어하지 않습니다.

예약 실행은 같은 revision의 이전 실패 때문에 차단되지 않습니다. 다음 예약 시점에 다시 실행하며, draft Knowledge 브랜치에 보존된 완료 페이지가 있으면 이를 입력 baseline으로 사용합니다. 생성 실패나 source 변경은 부분 페이지를 draft로 push한 뒤 workflow 실패로 끝납니다. 출력 범위 위반은 push 전에 차단합니다. Git 또는 PR API가 실패하면 exact lease로 이전 브랜치와 기존 PR 상태 복원을 시도하며, 복원까지 실패한 원격 장애는 Actions 로그에서 확인해야 합니다. OpenWiki 내부의 페이지 복구와 증분 생성 판단은 OpenWiki가 담당합니다.

workflow는 패키지에 포함된 lee-spec-kit-technical-writing 스킬을 임시 OpenWiki 설정 디렉터리에 복사하지만, 이를 검증기나 재시도 제어기로 사용하지 않습니다. provider와 모델은 OpenWiki 환경 변수 및 repository secret으로 설정합니다. 기본 scaffold는 OPENAI_API_KEY를 참조하며 다른 OpenAI-compatible provider를 사용할 때는 생성된 workflow를 프로젝트가 직접 수정합니다. PR 생성과 branch push에는 OPENWIKI_PR_TOKEN을 사용합니다. 대상 저장소의 Contents 및 Pull requests 읽기/쓰기 권한만 가진 fine-grained token 또는 GitHub App token을 등록합니다.

Knowledge 최신성은 Feature 완료를 막지 않습니다. experimental.openwiki=false 또는 플래그 누락 시 scaffold를 만들지 않습니다. 기존 knowledge publish, update, sync, apply, status, doctor, audit 명령과 lee-spec-kit receipt는 제거되었습니다. 기존 생성 문서는 삭제하지 않으며 OpenWiki가 다음 실행에서 baseline으로 사용할 수 있습니다.

Docs

• Public CLI Reference
• Agent CLI Reference
• Internal CLI Reference
• Codex Hooks Integration
• Migration Guide
• Reference Index

License

코드와 일반 패키지 내용은 MIT입니다. 번들된 OpenWiki 기술 글쓰기 스킬은 Toss의 Technical Writing을 각색한 자료로, 해당 스킬 디렉터리에 한해 CC BY-NC-SA 4.0이 적용됩니다. 자세한 범위와 출처는 THIRD_PARTY_NOTICES.md를 참고하세요.

Feature ID와 협업

새 GitHub Feature는 Issue부터 선택하거나 생성합니다. feature login --issue 123은 123-login 문서를 만들고, 브랜치는 feat/123-login, 커밋 범위는 #123을 사용합니다. 새 Issue가 필요하면 제목과 본문을 먼저 공유한 뒤 feature login --create-issue --desc "문제와 기대 결과" --confirm OK를 실행합니다. Issue 생성은 구현 승인이 아닙니다. Spec·Plan 승인과 리뷰 절차는 그대로 적용됩니다.

local 모드에서는 feature login이 K7M2Q9RX4DAB-login 같은 12자리 무작위 ID를 생성합니다. 중앙 순번이나 폴더 정렬 순서는 실행 순서가 아닙니다. 기존 F001 문서는 계속 사용할 수 있으며 --id F001은 기존 자료를 가져오는 호환 경로로 남습니다. 신규 Feature의 .feature.json에는 고정 ID, Issue URL, 브랜치, 담당자를 기록합니다. --owner를 생략하면 Git 이메일을 사용합니다.

한 Feature는 한 담당자가 맡고, 다른 Feature는 병렬로 개발할 수 있습니다. 신규 Feature는 코드 worktree를 사용합니다. standalone에서는 Feature 생성 직후 workflow-stage가 안내하는 workspace prepare <id>를 실행합니다. 이 명령이 해당 Feature seed만 커밋하고, 반환된 docsDirectory에서 문서를 작성합니다. 코드 worktree는 기존 승인 절차 후 생성됩니다. 두 저장소를 한 번에 원자적으로 병합하지는 않습니다. local은 코드 통합 검증 → 문서 통합 → 정리 순서로 Feature를 완료합니다. OpenWiki 갱신은 그 통합 revision을 대상으로 독립 실행되며 실패해도 완료된 통합을 되돌리지 않습니다.

상태 변경은 다음 명령을 사용합니다.

npx lee-spec-kit task claim <id> --json
npx lee-spec-kit task status <id> --json
npx lee-spec-kit task transition <id> <task-id> --from TODO --to DOING --session <발급된-token> --expected-hash <tasks.md-hash> --json
npx lee-spec-kit task release <id> --session <발급된-token> --json

세션은 같은 로컬 저장소의 worktree들이 공유합니다. 다른 기기 사이에는 GitHub Issue 담당자와 PR 리뷰를 기준으로 조율합니다. 담당자 변경은 기존 세션을 해제한 뒤 .feature.json의 owner 변경을 리뷰합니다. Markdown을 직접 편집하는 도구까지 잠그지는 않으므로, 상태 변경 명령은 읽었던 문서 해시가 달라지면 중단합니다. 토큰을 잃어버린 경우 실행 중인 작업이 없는지 확인한 뒤 Git common directory의 lee-spec-kit.runtime/locks/session-*.json을 수동 정리할 수 있습니다.

base가 앞서가면 local sync <id> 또는 workspace sync-docs <id>로 해당 Feature 작업 공간에 반영하고 충돌을 해결한 뒤 다시 검증합니다. PR 병합 실패 시 자동 rebase·force-push를 하지 않습니다. 로컬 통합은 공통 저장소 잠금으로 직렬화하며, 검증 중 브랜치·파일이 달라지면 변경을 보존하고 중단합니다. 실패한 squash의 작업 내용도 자동 삭제하지 않습니다.

CI에서는 npx lee-spec-kit feature-audit --base-ref origin/main --enforce --json을 실행해 중복 ID, 고정 식별자 변경, 문서와 메타데이터 불일치, 한 Feature의 중복 활성 Task를 검사할 수 있습니다. 먼저 대상 base를 fetch해야 합니다. workflow-stage --json의 sharedDocumentationWarnings는 현재 문서에서 발견한 PRD·아키텍처 수정 대상의 중복을 알려주며, 의미상의 충돌은 최신 base와 함께 리뷰해야 합니다.

새 embedded Feature는 workspace prepare가 해당 Feature seed만 커밋하고 managed worktree를 만든 뒤 그 경로를 반환합니다. 다른 staged 파일은 이 제한된 seed 커밋에 포함하지 않습니다. standalone 문서 통합은 내용 변경 없는 기록용 커밋을 남겨, 문서 저장소를 새로 clone하거나 로컬 캐시를 지워도 Git 이력에서 통합 근거를 복원합니다.

experimental.openwiki=true만으로 GitHub CI가 설치되지는 않습니다. knowledge ci가 만든 workflow를 커밋하고 provider secret과 OPENWIKI_PR_TOKEN을 설정해야 합니다. 예약 실행 또는 수동 workflow_dispatch에서 생성하며, Feature 완료 전략과 독립적으로 동작합니다. standalone GitHub 프로젝트의 CI는 코드 저장소 기준으로 실행되며 외부 문서 저장소 통합과 독립적이고, 외부 문서를 생성 입력 snapshot에 포함하지 않습니다.