agent-wiki

여러 프로젝트에서 하나의 지식 저장소를 공유할 수 있도록 위키 저장소를 생성하고 심볼릭 링크로 연결하는 스킬이다.

핵심 개념

• 위키 저장소: 설계 문서, 아키텍처 원칙 등을 모아두는 독립된 Git 저장소
• 심볼릭 링크: 각 프로젝트 루트에 .wiki라는 고정된 이름으로 위키 저장소를 연결
• 위키 저장소는 자체적으로 Git 버전 관리를 하므로, 소스코드 프로젝트의 .gitignore에 .wiki를 등록하여 이중 추적을 방지한다

워크플로우

1. 새로운 위키 저장소 생성

사용자가 위키 저장소 생성을 요청하면, 먼저 현재 환경을 확인한다.

사전 확인

진행 순서

1. 현재 프로젝트의 이름과 위치를 파악한다
2. 상위 디렉토리와 같은 레벨에 [프로젝트명]-wiki 폴더를 생성한다
   • 예: 프로젝트가 ~/Workspace/my-app이면 → ~/Workspace/my-app-wiki
   • 사용자가 다른 이름이나 위치를 원하면 그에 따른다
   • 동일한 이름의 폴더가 이미 존재하면 생성을 중단하고 사용자에게 안내한다. 기존 폴더가 위키 저장소라면 연결 단계로 안내한다
3. references/contributing-template.md를 읽고 위키 저장소에 CONTRIBUTING.md로 생성한다
4. Git 저장소로 초기화하고 첫 커밋을 만든다
   • 위키 폴더의 상위 디렉토리가 Git 저장소인 경우, 위키 폴더가 의도치 않게 추적될 수 있다. 상위 저장소의 .gitignore에 위키 폴더명을 등록할지 사용자에게 확인한다
5. CWD가 소스코드 프로젝트(Git 저장소이면서 위키가 아닌 환경)라면, 이어서 심볼릭 링크 연결 단계로 진행한다
   • CWD가 빈 디렉토리이거나 프로젝트가 아닌 경우에는 위키 생성만 완료하고 종료한다. 추후 프로젝트에서 심볼릭 링크 연결을 별도로 진행할 수 있음을 안내한다

2. 심볼릭 링크 연결

위키 저장소를 소스코드 프로젝트에 연결하는 단계다. 새로 생성한 직후이거나, 기존 위키 저장소를 다른 프로젝트에 연결하거나, 폴더명 변경이나 링크 깨짐으로 재연결이 필요한 경우 모두 이 단계를 따른다.

CWD가 위키 저장소 자체(*-wiki 패턴이거나 위키 형식의 CONTRIBUTING.md가 존재)이면, 소스코드 프로젝트에서 실행하도록 안내하고 중단한다.

1. 위키 저장소의 실제 경로를 확인한다
   • 새로 생성한 경우: 바로 위에서 만든 경로
   • 기존 저장소 연결: 상위 디렉토리에서 *-wiki 패턴으로 탐색하거나, 사용자에게 경로를 직접 물어본다
   • 재연결: 기존 .wiki 링크가 가리키던 경로를 확인하고, 실제 저장소 위치를 사용자에게 확인받는다
   • *-wiki 후보가 여러 개이면 목록을 보여주고 사용자에게 선택을 요청한다
   • 사용자가 경로를 직접 제공한 경우, 반드시 절대경로로 변환하여 사용한다. 상대경로로 심볼릭 링크를 만들면 CWD 변경 시 깨질 수 있다
2. 프로젝트 루트에 .wiki 심볼릭 링크를 생성한다
   • OS와 셸 환경에 따라 명령이 다르다. references/symlink-guide.md를 참고하여 적절한 명령을 사용한다
   • 실패 시에도 가이드에 대안이 정리되어 있으므로 순서대로 시도한다
   • .wiki가 이미 존재하는 경우:
     • 정상 동작하는 심볼릭 링크이면, 현재 연결 대상을 보여주고 덮어쓸지 사용자에게 확인한다
     • 깨진 심볼릭 링크이면, 삭제 후 새로 생성한다
     • 심볼릭 링크가 아닌 실제 디렉토리나 파일이면, 절대로 삭제하지 않는다. 사용자에게 상황을 설명하고 수동 조치를 요청한다
   • 생성 후 링크가 대상을 정상적으로 가리키는지 검증한다 (ls -la .wiki 등)
3. .gitignore에 .wiki를 등록한다 (이미 등록되어 있으면 생략)
   • .gitignore 파일이 없으면 새로 생성한다
   • CWD가 Git 저장소가 아니면 이 단계를 건너뛴다