git의 로컬 클론(Local Clone) 수를 세어보니 29개가 있었습니다. 개인 OSS가 19개, 개인 앱이 6개, 업무 프로젝트가 4개. 전부 동시에 커밋하는 것은 아니지만, 최근 30일 동안 한 번이라도 만진 것만 해도 29개입니다. 이것을 음성 입력으로 다루려고 했더니, 우선 이름에서 막혔습니다.

AI CLI에 "manabi-map의 다음 작업을 해줘"라고 말하면, AI는 당연히 manabi-map을 모르기 때문에 "어떤 리포지토리인가요?"라고 되묻습니다. "메니 에이아이 씨엘아이" 같은 발음은 애초에 음성 입력에서 오인식될 확률이 높습니다. 긴 영문 리포지토리 이름과 음성 입력의 궁합은 절망적으로 나쁩니다.

이 기사는 그것을 하룻밤 만에 해결한 메커니즘에 관한 이야기입니다. 새로 만든 것은 CSV 파일 2개와 기존 skill에 내용을 추가한 것뿐입니다. 구조는 가볍지만, 판단의 핵심 포인트는 적어둘 가치가 있다고 느껴서 남겨둡니다.

참고로, 후반부에 나오는 "오늘 할 일 1개"를 선택하게 하는 부분은 자작 OSS인 docsweep을 전제로 하고 있습니다. AI 코딩 툴(Claude Code / Codex 등)이 양산하는 plan_*.md / bugfix_*.md / pending_*.md의 축적과 노후화를 H1 상태 라벨과 OKF frontmatter로 기계적으로 처리하는 CLI + Web UI입니다. 같은 고민을 하시는 분은 pip install docsweep으로 설치할 수 있습니다. 리포지토리는 여기 있습니다 (Star를 눌러주시면 힘이 됩니다): github.com/ishizakahiroshi/docsweep

음성 입력으로 AI CLI를 사용하기 시작한 지 며칠 만에 깨달은 것은, 리포지토리 이름은 "말하기 위해" 설계되지 않았다는 것이었습니다. many-ai-cli, claude-code-context-diet, tab-title-prefix, vite-plugin-git-version 등. 문자로 읽을 때는 전혀 문제가 없습니다. 오히려 검색성을 높이기 위해 일부러 고유성을 강화한 명명 방식을 사용하고 있습니다.

하지만 음성으로 "클로드 코드 컨텍스트 다이어트"라고 말하면, 인식 결과는 매번 흔들립니다. "클라우드"가 되기도 하고 "클로트"가 되기도 합니다. 가타카나와 영문이 섞이면 더욱 왜곡됩니다.

이 시점에서 선택지는 3가지가 있었습니다.

• 리포지토리 이름을 짧게 다시 짓는다 (기존의 GitHub URL / npm / import path가 전부 깨진다. 논외)
• 음성 입력을 포기하고 키보드로 작성한다 (애초에 음성으로 빠르게 하고 싶었던 목적이 사라진다)
• 호칭 인덱스(Alias Index)를 사이에 둔다 (발화 → 정식 리포지토리 이름(canonical slug)으로의 변환 중간층을 만든다)

3번째입니다. IME의 사전 등록과 비슷한 발상이지만, AI CLI에서 사용할 수 있도록 독립된 파일에 둡니다.

전제로, 저는 개인 지식을 "사람·회사·서버·시스템"이라는 4장의 얇은 CSV(kb)로 관리하고 있으며, AI에게는 주제에 따라 몇 줄만 참조하게 하고 있습니다. 자세한 내용은 이전 Zenn 기사에 썼습니다 (조직의 암묵지는 4장의 CSV로 충분하다 / 5번째인 호칭 인덱스로 음성 입력의 표기 불일치를 흡수한다). 이 기사는 그 5번째 호칭 인덱스를 dev 리포지토리에도 확장한 이야기입니다.

흥미로웠던 점은, 이것과 동일한 문제를 약 10일 전쯤 다른 맥락에서 해결하고 있었다는 것입니다. 회사 이름이나 사내 시스템 이름이 음성 입력 시 매번 무너지기 때문에, kb-alias-add라는 작은 skill을 만들어 CSV 파일 1개로 흡수하는 메커니즘을 이미 만들어 두었습니다.

구조는 매우 작습니다.

alias,ref_type,ref_id,ref_name,note
わかば,application,x001,若葉商事(受注管理),음성 입력 오인식
HR,application,x002,ハーモニー(人事),사내 약칭

"별칭 → 참조 대상"의 대응표를 추가해 나갈 뿐입니다. skill은 한 줄을 추가하는 얇은 래퍼(Wrapper)입니다. 장부 본체(applications / people / servers 등)를 더럽히지 않고, 인덱스 측에서 흡수합니다.

여기에 ref_type=project를 추가하는 것만으로, 그대로 dev 리포지토리의 호칭 불일치 흡수에 유용하게 사용할 수 있었습니다. 새로 설계하는 것이 아니라, 이미 작동하고 있는 메커니즘에 1가지 타입을 추가하는 것이 최단 경로였습니다.

구성 방식은 다음과 같습니다.

Google Calendar = 시간 블록. "오늘 14:00-17:00는 many-ai-cli" 정도의 입도로 대략적으로. 이벤트 타이틀 앞에 [many-ai-cli]

처럼 슬래그를 전치 -
docsweep = 개별 태스크. plan_*.md

/bugfix_*.md

/pending_*.md

을 각 리포지토리 하위에 배치합니다. docsweep brief로 오늘 할 1개를 확정합니다 -
kb-local/aliases.csv + projects.csv = 호칭 인덱스. 음성 입력의 오변환을 공식 리포지토리 이름으로 변환 -
team-log.csv = 실적(후술)

docsweep은 제가 만든 OSS로, plan_*.md에 due:를 작성하여 '오늘 할 1개'를 선택하게 하는 도구입니다. 이 자체의 소개는 본론이 아니므로, 요컨대 '태스크 장부의 md 기반 버전'이라고 생각하시면 됩니다.

Calendar는 '시간 블록'으로만 존재합니다. 여기가 나중에 효과를 발휘합니다.

호칭 해결 과정은 2단계 구조로 만들었습니다.

• 음성으로 '마나비맵의 다음을 진행해줘'를 받음
• kb-local/aliases.csv를 grep 합니다. alias 열에 일치하는 것이 있으면 ref_id (= 공식 리포지토리 이름)로 해결하여 그대로 실행합니다. - 일치가 없으면 projects.csv의 name에서 퍼지 매치(부분 일치・가타카나↔영문자 변환)를 합니다. - 단일 후보가 발견되면 'manabi-map이 맞나요?(Y/N)'라는 질문을 1회 던집니다. Yes라면 실행하고 + 이어서 'kb-local에 등록할까요?(Y/N)'로 추가까지 일관되게 진행합니다.

한 번에 추가하지 않는 것이 포인트입니다. 인간 측에서 '이번에는 다른 프로젝트였다'라고 거절할 여지를 남겨두는 것입니다. 한 번 등록되면 다음부터는 질문을 받지 않기 때문에, 오등록은 번거롭습니다.

이렇게 하면 운영 시작 시점에 aliases.csv가 비어 있어도 괜찮아졌습니다. 사용하면서 오변환에 직면했을 때 1줄씩 추가하면 됩니다. 사전에 전체 29개 리포지토리의 별명을 3가지 패턴으로 등록하는 같은 무거운 초기 작업은 필요 없습니다.

작은 실수도 적어둡니다. 장부의 위치를 정할 때, 이렇게 제안했습니다.

'회사 업무 리포지토리 이름은 고객명을 포함할 수 있으니, 공개 kb와 별도의 비공개 kb-local로 분리합시다'

이것은 절반은 맞고 절반은 틀렸습니다. **

는 long 형식으로 했습니다.

date, owner, project, hours, note
2026-07-20, ishiz, acme, 6,
2026-07-20, ishiz, many-ai-cli, 2, v0.4 작업

1행 = 1일 × 1인 × 1안건. 빈칸은 「행을 쓰지 않음」으로 표현. 현재의 운용 시트는 wide 형식 (열 = 날짜)으로 인간의 육안 확인에는 유리하지만, AI로 행을 추가하려면 열 인덱스 (column index)를 매번 계산해야 하며, 이것이 은근히 까다롭습니다.

wide 형식을 버려서 곤란한 점은 「월간 집계(monthly aggregation)를 어떻게 내는가」이지만, 이것은 AI에게 맡기면 해결됩니다.

지난달 안건별 집계해줘

pandas나 PowerShell의 Import-Csv | Group-Object

로 3줄의 스크립트가 실행되어, Markdown 표로 돌아옵니다. 회사 보고용으로 붙여넣으려면 그대로 붙여넣으면 됩니다. 시각화가 필요하다면 「HTML 표로 출력해줘」라고 말하면 표가 됩니다.

"집계 테이블을 수동으로 유지보수한다"라는 태스크를 통째로 없앨 수 있었다는 점이 컸으며, 이는 아마 xlsx를 직접 운용하는 것보다 훨씬 편할 것입니다.

물론 한계도 있습니다. 실시간 대시보드로서 상시 보고 싶다면 피벗(pivot)이나 BI 툴이 적합합니다. 타인이 만지는 집계 템플릿이라면 Excel이 빠릅니다. 개인이 월간 단위로 되돌아보는 용도라면 AI 집계로 충분하다는 식의 구분입니다.

마지막으로 하나만 더, 운용 설계의 자세에 대한 이야기입니다.

호칭 인덱스 aliases.csv

는 오늘 시점에서 빈 상태로 운용을 시작했습니다. 29개 리포지토리 분량의 별칭을 예측하여 사전에 투입할 수도 있었지만, 그렇게 하지 않았습니다.

이유는 단순합니다. 실제로 내가 오인식(misconversion)하는 호칭은 직접 써보지 않으면 알 수 없기 때문입니다. 「마나비맵」이라고 말할지 「마나비맛푸」라고 말할지, 「메니에이아이」라고 줄여 말할지 「메니에이아이씨엘아이」라고 전부 말할지는 책상 위에서 결정할 수 없습니다. 사용하기 시작한 지 1주일 만에 자연스럽게 필요한 10여 개가 쌓이는 편이, 사전에 등록한 100개보다 확실히 정밀도가 높을 것입니다.

장부를 "만들어 두는" 운용이 아니라, "운용 속에서 키워 나가는" 설계. 이것은 docsweep에서도 kb-alias-add에서도 계속 같은 자세로 만들고 있으며, 아마 이런 타입의 개인용 도구에서는 공통된 핵심 포인트라고 생각합니다.

• 음성 입력과 긴 영문 리포지토리 이름의 상성이 나쁜 문제는, 중간층에 호칭 인덱스를 한 장 끼워 넣는 것만으로 해결된다.

• 이미 다른 맥락에서 해결해 둔 메커니즘은, 신규 설계보다 "한 가지 타입을 추가하는 것"이 빠르다 (이번에는 ref_type=project 추가만).

• 장부의 분리 기준은 「기밀도」가 아니라 「공유 범위」. 공유 대상의 실체를 먼저 한 번 확인하는 것이 전부.

• xlsx 직접 운용은 AI 쓰기 시 파일 잠금(file lock)과 바이너리 diff 불가라는 2대 지뢰가 있다. CSV 원본 + Excel로 열기로 양립.

• 집계는 AI에게 그 자리에서 부탁하면 된다. "집계 테이블을 수동으로 유지보수한다"를 통째로 없애는 것이 xlsx 피벗을 유지하는 것보다 편하다.

• 장부는 사전에 투입하지 않고 사용하면서 키워 나간다. 실제 오인식 패턴은 책상 위에서 예측할 수 없다.

• AI 코딩 툴이 뱉어낸 plan_*.md / bugfix_*.md가 각 프로젝트에 흩어져 있어, 어떤 것이 살아있고 어떤 것이 죽었는지 알 수 없는 사람

• 여러 프로젝트를 가로질러 「오늘 딱 1개만」을 기계적으로 선택하게 하고 싶은 사람

• md의 frontmatter를 OKF (Open Knowledge Format) 호환으로 맞춰서, 다른 툴과도 함께 읽어 들이고 싶은 사람

• 호칭 인덱스와 조합하여, 음성만으로 프로젝트 사이를 넘나들고 싶은 사람

pip install docsweep

으로 1분 만에 설치됩니다. 설정 없이 바로 작동합니다.

• 리포지토리 (Issue / PR 환영): github.com/ishizakahiroshi/docsweep
• PyPI: pypi.org/project/docsweep

그 외에도 음성·AI 연동 관련 작은 툴들을 몇 가지 공개하고 있습니다. 개인 사이트인 ishizakahiroshi.com의 Works에서 모아 볼 수 있습니다.

29개 리포지토리의 관리가 「어렵다」기보다 「발음이 어렵다」는 점 때문에 막혀 있었던 것이 솔직한 심정이었습니다. 설계로서는 CSV 2장과 skill 추가뿐입니다. 도해를 담은 HTML을 한 장 생성하면, 나머지는 운용 속에서 자라납니다.

같은 증상으로 어려움을 겪고 있는 사람이 있다면, 아마 비슷한 메커니즘을 30분 만에 만들 수 있을 것입니다. 정식 리포지토리 (repo) 명의 대장과 별칭 인덱스(alias index) 2개의 파일, 그리고 "별칭을 한 줄 추가한다"는 것뿐인 작은 스킬 (skill), 그것뿐입니다.

작게. 운용 속에서 자라나는 대장을 앞으로도 계속 늘려가겠습니다.

작성자: ishizakahiroshi

시골 재택 수탁 엔지니어. 백엔드 (Backend)・인프라 (Infrastructure)・AI 연동을 중심으로, 업무 위탁을 통해 개인 개발 도구를 만들고 있습니다. 캐주얼한 상담 환영합니다.

• 사이트: https://ishizakahiroshi.com/
• GitHub: https://github.com/ishizakahiroshi
• X: https://x.com/ishizakahiroshi

※ 헤더 이미지와 인포그래픽 (Infographic)은 AI (이미지 생성)로 작성하고 있습니다.

※ 본문의 삽화도 AI (이미지 생성)로 작성하고 있습니다.