SpeechDown CLI: 소프트웨어 설계와 AI 협업의 실험장

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

개발 툴

대상자

• 소프트웨어 아키텍처, 도메인 주도 설계(DDD), AI 협업 개발에 관심 있는 개발자
• 중급 이상의 Python 및 CLI 도구 개발 경험 보유자

핵심 요약

• 도메인 주도 설계(DDD)와 Ports & Adapters(육각형) 패턴을 기반으로 핵심 로직과 I/O를 분리하여 유연한 아키텍처 구현
• Architecture Decision Records (ADRs)와 디자인 문서(PRDS)를 통해 AI 협업 시 설계 일관성 유지
• AI-rules.md 파일을 통해 명명 규칙, 테스트 기준, 아키텍처 구조를 자동으로 AI 도구에 적용

섹션별 세부 요약

1. 목적 및 배경

• 개인용 CLI 툴로 음성 메모를 타임스탬프 기반의 Markdown으로 변환
• AI 협업 개발을 위한 실무적 사례로, 기존 voice-cli 프로젝트의 자연 연장
• 현재 상태: Pre-v1 단계로, 학습 및 실험용으로 적합

2. 아키텍처 설계

• 4단계 계층 구조: domain (핵심 로직), application (인터페이스 정의), infrastructure (구현), presentation (CLI)
• Ports & Adapters 패턴 적용: 예) TimestampPort 인터페이스와 FileTimestampAdapter 구현
• 의존성 방향: domain → application → infrastructure로 단일 방향 유지

3. 개발 프로세스

• ADRs로 설계 결정 사유 문서화 (예: docs/adrs/ 디렉토리)
• 디자인 문서(PRDS) 작성: AI 도구와 협업 시 구체적 구현 방향 제시

4. AI 협업 모델

• 디자인 문서를 AI(예: GitHub Copilot, Claude)의 입력으로 활용
• AI-rules.md 파일을 기반으로 구성 요소 규칙 자동 생성 (예: .github/copilot-instructions.md)

5. 기능 및 사용 예시

• 명령어: sd transcribe --within-hours 24 → 최근 24시간 내 음성 파일을 Markdown 변환
• 확장성: 새로운 음성 인식 엔진 추가 시 adapter 구현만으로 가능

결론

• SpeechDown은 실무적 소프트웨어 아키텍처와 AI 협업 개발을 결합한 예시로, ADRs와 PRDS 문서화, Ports & Adapters 패턴 적용이 핵심
• AI 협업 시 디자인 문서를 명확히 작성하고 AI-rules.md를 활용하여 프로젝트 일관성 유지가 권장됨