Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
mini 도구의 프로젝트 건강 상태를 관리하는 두 가지 명령어인 changelog와 doctor의 사용법을 설명합니다. changelog는 변경 이력을 확인하고, doctor는 프로젝트 설정 및 상태의 무결성을 점검합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기파트 7에서는 계기판(instrument panel)을 다루었습니다. 즉, '내가 어디에 있는지', '한 단계 뒤로', '어떤 모델인지'를 확인하는 기능이었죠. 이제 두 개의 명령어가 남았습니다. 이 명령어들은 프로젝트의 상태(phase state)가 아니라, 전체적인 구조가 잘 유지되고 있는지, 즉 프로젝트의 '건강 상태(health)'를 감시합니다. 바로 changelog(사용자를 위해 무엇이, 언제 변경되었는지)와 doctor(mini 설정이 제대로 되어 있는지)입니다. 두 명령어 모두 읽기 전용(read-only)이며, Claude를 사용하지 않습니다.
changelog — 쌓여온 변경 사항들파트 4를 기억하시나요? 모든 done 명령은 CHANGELOG.md에 새로운 항목을 제안합니다. 네 단계를 거치고 나면 그곳에는 꽤 많은 내용이 쌓이게 되며, changelog는 파일을 직접 열지 않고도 그 내용을 보여줍니다:
mini changelog
[Unreleased]
### Added
...
단순히 mini changelog라고 입력하면 가장 최근에 출시된(released) 버전을 보여줍니다. 하지만 pycalc는 아직 아무것도 출시하지 않았습니다(버전을 올린 적이 없습니다. 파트 6에서 --bump/--push는 선택 사항이라고 언급했었죠). 따라서 이 명령어는 날짜가 지정된 버전이 없음을 감지하고, 솔직하게 해당 노트를 포함하여 [Unreleased] 섹션을 보여줍니다. 특정 내용을 확인하고 싶을 때는 다음과 같이 입력합니다:
mini changelog --unreleased # 대기 중인 변경 사항
mini changelog --version 1.0.0 # 특정 릴리스 버전
mini changelog --all # 파일 전체 내용
중요한 세부 사항: changelog는 .mini/ 디렉토리와 독립적입니다. 단순히 현재 디렉토리의 CHANGELOG.md를 읽을 뿐입니다. 따라서 mini와 전혀 관련이 없는 프로젝트에서도 작동합니다. 이는 상태(state)의 일부가 아니라 단순한 리더(reader)입니다.
doctor — 설정이 제대로 되어 있는가?doctor는 프로젝트를 훑으며 체크리스트를 출력합니다. 무엇이 정상인지, 무엇이 경고인지, 무엇이 고장 났는지, 그리고 각 문제에 대해 어떻게 수정해야 하는지를 보여줍니다:
mini doctor
mini doctor
✓ Project: state schema v2
✓ Phases: no orphaned "doing" phases
...
무엇을 점검하는지, 그리고 이것이 왜 유용한지에 대해:
state.json 버전이 이 mini가 읽을 수 있는 버전과 일치합니까? 일치하지 않는다면 mini migrate를 제안합니다. (이것은 실제로 작업을 중단시키는 유일한 fail입니다.)doing 상태로 멈춰 있습니까? 이것이 파트 4-5에서 보았던 "stuck" 상태입니다; doctor는 이를 찾아내어 done 또는 undo를 제안합니다.undo 이후)로부터 .mini/run/ 또는 .mini/decisions/에 남겨진 고립된(orphaned) 파일이 있습니까? 삭제해도 안전합니다./mini:* 세트가 프로젝트에 설치되어 있습니까? pycalc의 경우 이것이 **누락(missing)**되어 있습니다 — 이는 오류가 아니라 정당한 상태입니다: pycalc는 사용자 범위(user-scope) 명령(파트 0)으로 실행되므로, 프로젝트 범위(project-scope) 명령을 가지고 있지 않습니다. 이것이 ✗(에러)가 아닌 !(경고)인 이유입니다.doctor는 제가 v1.18.0을 실행하는 동안 v1.20.0이 출시되었다고 방금 알려주었습니다.요약은 개수를 집계합니다: pycalc의 경우, "모든 필수 요소가 존재함, 경고 2개" — 치명적인 것은 없으며, 고려해야 할 두 가지 사항이 있다는 뜻입니다. doctor는 순수하게 읽기 전용 진단 도구입니다; 스스로 아무것도 수정하지 않으며, 단지 보여주고 조언할 뿐입니다.
실행 시점:
undo/migrate이후(무언가 남겨진 것이 없는지 확인하기 위해), mini 업데이트 이후, 또는 단순히 무언가 이상하다고 느껴져서 문제가 설정에 있는 것이 아닌지 빠르게 확인하고 싶을 때 실행하세요.
파트 7의 상태(state) 명령들과 동일한 패턴을 따릅니다: 읽기 전용, 로컬, 토큰 소모 제로. changelog는 CHANGELOG.md를 읽고, doctor는 파일 시스템과 버전 캐시를 읽습니다. 둘 다 Claude를 실행하지 않으며, 아무것도 변경하지 않습니다. 이들은 대시보드의 경고등과 같습니다 — 원할 때 슥 훑어보고 넘어가면 됩니다.
doctor는 코드가 아닌 설정을 점검합니다. 7개의 초록색 체크 표시가 프로그램이 작동한다는 것을 의미하지는 않습니다. 이는 mini가 정상 상태임을 의미할 뿐입니다. "테스트를 통과했는가?"는 여전히 여러분의 몫이며 verify의 역할입니다.changelog는 done이 작성한 만큼만 유용합니다. 이 명령은 CHANGELOG.md에 기록된 내용을 보여주며, 해당 내용은 done 세션에서 생성됩니다. 그곳에 모호한 항목을 남겨두면 changelog도 똑같이 모호하게 전달합니다. 이것은 독자(reader)이지 교정자(proofreader)가 아닙니다.doctor 경고는 명령이 아닙니다. "Slash commands: none"이라는 메시지는 pycalc(사용자 범위)의 경우 괜찮습니다. 힌트를 반드시 해결해야 할 할 일 목록(TODO list)이 아닌 제안으로 취급하세요. 여러분은 문맥을 알고 있지만, 체크리스트는 알지 못합니다.이것으로 init부터 전체 루프, 자율 모드(autonomous mode), 상태(state) 및 상태 점검(health)까지 모든 세트가 완료되었습니다. 이제 한 가지 시나리오가 남아 있는데, 지금까지는 피해 왔던 것입니다. 만약 프로젝트가 이미 실행 중이고, 나중에 mini를 도입하고 싶다면 어떻게 해야 할까요? 그것이 바로 파트 9 — import-gsd, audit, 그리고 map입니다. 기존 코드베이스에 mini를 설정하는 세 가지 방법입니다. 그리고 피날레인 만큼, GitHub에 pycalc를 공개할 예정입니다. 단순히 "또 하나의 계산기"로서가 아니라, 이 시리즈 전체에서 설명한 파일들인 .mini/의 비전, 백로그(backlog), 단계별 메모리(phase memories) 및 실행 보고서(run reports)를 보여주는 오픈 쇼케이스로서 공개할 것입니다.
mini는 오픈 소스입니다: npm install -g mini-orchestrator를 실행한 후, 프로젝트에서 mini install-commands를 입력하세요. 소스 코드와 문서는 GitHub에서 확인할 수 있습니다.