설치 가이드

요구 사항

Python 3.11 이상
Claude Code, Codex CLI, Gemini CLI 중 하나 이상
기본 검사에는 외부 Python 패키지가 필요하지 않습니다. 개발 테스트에는 pytest가 필요합니다.

자동 설치

저장소 루트에서 실행합니다.

./install.sh

설치된 도구를 감지해 다음 위치에 같은 canonical skill을 연결합니다.

Claude Code: Claude skills 디렉터리 + agents/*.md
Codex CLI: Codex skills 디렉터리
Gemini CLI: extension link

먼저 확인만 하려면 다음을 실행합니다.

./install.sh --dry-run

주요 옵션

--copy          Claude/Codex에서 심볼릭 링크 대신 파일 복사
--claude-only   Claude만 설치
--codex-only    Codex만 설치
--gemini-only   Gemini만 설치
--no-gemini     Gemini 설치 생략
--force         충돌 대상을 타임스탬프 백업한 뒤 설치
--dry-run       변경 없이 예정 작업 출력

--copy는 Claude/Codex 설치에만 적용됩니다. 이 복사본은 저장소와 연결되지 않으므로 자동 제거 대상이 아니며, 업데이트하려면 다시 복사 설치해야 합니다. Gemini 확장은 CLI의 extension link 방식만 사용합니다.

Gemini 공개 명령은 사용자 작업 디렉터리의 상대경로를 사용하지 않습니다. 확장이 등록한 technical-doc-flow 스킬을 활성화하고, 활성화된 SKILL.md의 디렉터리를 런타임 경로로 사용합니다. gemini-extension.json의 contextFileName이 GEMINI.md를 명시하므로 실행 규칙도 확장 위치에서 로드됩니다.

수동 설치

canonical skill 디렉터리는 다음입니다.

skills/technical-doc-flow/

이 디렉터리를 사용하는 도구의 skills 폴더에 복사하거나 심볼릭 링크로 연결합니다. Claude Code에서 역할별 에이전트를 쓰려면 agents/*.md도 Claude agents 폴더에 연결합니다.

제거

./uninstall.sh --dry-run
./uninstall.sh

Claude/Codex 제거는 현재 저장소를 가리키는 심볼릭 링크만 지웁니다. 일반 파일, 다른 저장소의 링크, --copy로 설치한 디렉터리는 삭제하지 않습니다. Gemini 제거는 gemini extensions list --output-format=json에서 확장 이름과 현재 checkout 경로가 모두 일치할 때만 uninstall을 실행합니다. 목록 조회나 소유권 확인에 실패하면 자동 삭제하지 않고 수동 확인 명령을 안내합니다.

업데이트

Git clone으로 받은 저장소라면 다음을 사용할 수 있습니다.

./update.sh

업데이트는 fast-forward만 허용하고, 매니페스트 계약과 생성 규칙 동기화가 실패하면 설치를 다시 적용하거나 완료로 보고하지 않습니다. 현재 디렉터리가 Git 저장소가 아니면 명확한 메시지와 함께 중단합니다.

문제 해결

스킬이 보이지 않으면 새 CLI 세션을 시작합니다.
충돌 파일이 있으면 먼저 내용을 확인하고, 보존해도 되는 경우에만 --force를 사용합니다.
quick-rules.md sync 오류는 해당 파일을 직접 고치지 말고 python3 scripts/build_quick_rules.py로 재생성합니다.
최종 문서가 있어도 09_final_report.json이 없거나 verdict가 pass가 아니면 실행은 완료되지 않은 것입니다.

3.3 KiB Raw Blame History