80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 설치 가이드
|
|
|
|
## 요구 사항
|
|
|
|
- Python 3.11 이상
|
|
- Claude Code, Codex CLI, Gemini CLI 중 하나 이상
|
|
- 기본 검사에는 외부 Python 패키지가 필요하지 않습니다. 개발 테스트에는 `pytest`가 필요합니다.
|
|
|
|
## 자동 설치
|
|
|
|
저장소 루트에서 실행합니다.
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
설치된 도구를 감지해 다음 위치에 같은 canonical skill을 연결합니다.
|
|
|
|
- Claude Code: Claude skills 디렉터리 + `agents/*.md`
|
|
- Codex CLI: Codex skills 디렉터리
|
|
- Gemini CLI: extension link
|
|
|
|
먼저 확인만 하려면 다음을 실행합니다.
|
|
|
|
```bash
|
|
./install.sh --dry-run
|
|
```
|
|
|
|
### 주요 옵션
|
|
|
|
```text
|
|
--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 디렉터리는 다음입니다.
|
|
|
|
```text
|
|
skills/technical-doc-flow/
|
|
```
|
|
|
|
이 디렉터리를 사용하는 도구의 skills 폴더에 복사하거나 심볼릭 링크로 연결합니다. Claude Code에서 역할별 에이전트를 쓰려면 `agents/*.md`도 Claude agents 폴더에 연결합니다.
|
|
|
|
## 제거
|
|
|
|
```bash
|
|
./uninstall.sh --dry-run
|
|
./uninstall.sh
|
|
```
|
|
|
|
Claude/Codex 제거는 현재 저장소를 가리키는 심볼릭 링크만 지웁니다. 일반 파일, 다른 저장소의 링크, `--copy`로 설치한 디렉터리는 삭제하지 않습니다. Gemini 제거는 `gemini extensions list --output-format=json`에서 확장 이름과 현재 checkout 경로가 모두 일치할 때만 uninstall을 실행합니다. 목록 조회나 소유권 확인에 실패하면 자동 삭제하지 않고 수동 확인 명령을 안내합니다.
|
|
|
|
## 업데이트
|
|
|
|
Git clone으로 받은 저장소라면 다음을 사용할 수 있습니다.
|
|
|
|
```bash
|
|
./update.sh
|
|
```
|
|
|
|
업데이트는 fast-forward만 허용하고, 매니페스트 계약과 생성 규칙 동기화가 실패하면 설치를 다시 적용하거나 완료로 보고하지 않습니다. 현재 디렉터리가 Git 저장소가 아니면 명확한 메시지와 함께 중단합니다.
|
|
|
|
## 문제 해결
|
|
|
|
- 스킬이 보이지 않으면 새 CLI 세션을 시작합니다.
|
|
- 충돌 파일이 있으면 먼저 내용을 확인하고, 보존해도 되는 경우에만 `--force`를 사용합니다.
|
|
- `quick-rules.md` sync 오류는 해당 파일을 직접 고치지 말고 `python3 scripts/build_quick_rules.py`로 재생성합니다.
|
|
- 최종 문서가 있어도 `09_final_report.json`이 없거나 verdict가 pass가 아니면 실행은 완료되지 않은 것입니다.
|