agent-wiki
여러 프로젝트에서 하나의 지식 저장소를 공유할 수 있도록 위키 저장소를 생성하고 심볼릭 링크로 연결하는 스킬이다.
핵심 개념
- 위키 저장소: 설계 문서, 아키텍처 원칙 등을 모아두는 독립된 Git 저장소
- 심볼릭 링크: 각 프로젝트 루트에
.wiki라는 고정된 이름으로 위키 저장소를 연결 - 위키 저장소는 자체적으로 Git 버전 관리를 하므로, 소스코드 프로젝트의
.gitignore에.wiki를 등록하여 이중 추적을 방지한다
워크플로우
1. 새로운 위키 저장소 생성
사용자가 위키 저장소 생성을 요청하면, 먼저 현재 환경을 확인한다.
사전 확인
| 상황 | 처리 |
|---|---|
CWD가 *-wiki 패턴이거나 CONTRIBUTING.md가 위키 형식 | 이미 위키 저장소일 수 있다. 사용자에게 확인하고, 맞다면 중단 |
CWD가 홈 디렉토리(~)나 시스템 디렉토리 | 프로젝트 경로를 사용자에게 물어본다 |
상위 디렉토리에 [프로젝트명]-wiki가 이미 존재 | 기존 위키를 사용할지(→ 연결 단계로), 새로 만들지 사용자에게 확인 |
상위 디렉토리에 다른 *-wiki 폴더가 존재 | 목록을 보여주고 기존 것을 쓸지 확인 |
진행 순서
- 현재 프로젝트의 이름과 위치를 파악한다
- 상위 디렉토리와 같은 레벨에
[프로젝트명]-wiki폴더를 생성한다
- 예: 프로젝트가 ~/Workspace/my-app이면 → ~/Workspace/my-app-wiki - 사용자가 다른 이름이나 위치를 원하면 그에 따른다 - 동일한 이름의 폴더가 이미 존재하면 생성을 중단하고 사용자에게 안내한다. 기존 폴더가 위키 저장소라면 연결 단계로 안내한다
references/contributing-template.md를 읽고 위키 저장소에CONTRIBUTING.md로 생성한다- Git 저장소로 초기화하고 첫 커밋을 만든다
- 위키 폴더의 상위 디렉토리가 Git 저장소인 경우, 위키 폴더가 의도치 않게 추적될 수 있다. 상위 저장소의 .gitignore에 위키 폴더명을 등록할지 사용자에게 확인한다
- CWD가 소스코드 프로젝트(Git 저장소이면서 위키가 아닌 환경)라면, 이어서 심볼릭 링크 연결 단계로 진행한다
- CWD가 빈 디렉토리이거나 프로젝트가 아닌 경우에는 위키 생성만 완료하고 종료한다. 추후 프로젝트에서 심볼릭 링크 연결을 별도로 진행할 수 있음을 안내한다
2. 심볼릭 링크 연결
위키 저장소를 소스코드 프로젝트에 연결하는 단계다. 새로 생성한 직후이거나, 기존 위키 저장소를 다른 프로젝트에 연결하거나, 폴더명 변경이나 링크 깨짐으로 재연결이 필요한 경우 모두 이 단계를 따른다.
CWD가 위키 저장소 자체(*-wiki 패턴이거나 위키 형식의 CONTRIBUTING.md가 존재)이면, 소스코드 프로젝트에서 실행하도록 안내하고 중단한다.
- 위키 저장소의 실제 경로를 확인한다
- 새로 생성한 경우: 바로 위에서 만든 경로 - 기존 저장소 연결: 상위 디렉토리에서 *-wiki 패턴으로 탐색하거나, 사용자에게 경로를 직접 물어본다 - 재연결: 기존 .wiki 링크가 가리키던 경로를 확인하고, 실제 저장소 위치를 사용자에게 확인받는다 - *-wiki 후보가 여러 개이면 목록을 보여주고 사용자에게 선택을 요청한다 - 사용자가 경로를 직접 제공한 경우, 반드시 절대경로로 변환하여 사용한다. 상대경로로 심볼릭 링크를 만들면 CWD 변경 시 깨질 수 있다
- 프로젝트 루트에
.wiki심볼릭 링크를 생성한다
- OS와 셸 환경에 따라 명령이 다르다. references/symlink-guide.md를 참고하여 적절한 명령을 사용한다 - 실패 시에도 가이드에 대안이 정리되어 있으므로 순서대로 시도한다 - .wiki가 이미 존재하는 경우: - 정상 동작하는 심볼릭 링크이면, 현재 연결 대상을 보여주고 덮어쓸지 사용자에게 확인한다 - 깨진 심볼릭 링크이면, 삭제 후 새로 생성한다 - 심볼릭 링크가 아닌 실제 디렉토리나 파일이면, 절대로 삭제하지 않는다. 사용자에게 상황을 설명하고 수동 조치를 요청한다 - 생성 후 링크가 대상을 정상적으로 가리키는지 검증한다 (ls -la.wiki 등)
.gitignore에.wiki를 등록한다 (이미 등록되어 있으면 생략)
- .gitignore 파일이 없으면 새로 생성한다 - CWD가 Git 저장소가 아니면 이 단계를 건너뛴다