jetpack-compose

AI 에이전트를 위한 Android CLI: 대규모 모바일 개발 환경에 적용하기 (새 탭에서 열림)

LINE Android처럼 수백 개의 Gradle 모듈과 대규모 코드를 가진 저장소에서는 단순한 `grep`·`glob` 검색만으로 AI 에이전트가 의미론적 질문에 답하기 어렵고, 불필요한 결과와 재시도로 토큰 비용이 급증합니다. LINE 개발팀은 Android CLI를 문서 검색과 Android Studio 연동의 기반으로 활용하되, 고정된 바이너리·래퍼·스킬·프롬프트를 조합해 보안, 환경 일관성, 오류 처리, 토큰 효율성을 보완하고 있습니다. 핵심은 CLI를 에이전트에 그대로 노출하지 않고, 저장소 규모와 조직 환경에 맞게 통제된 인터페이스로 제공하는 것입니다. ## 대규모 Android 저장소에서 AI 에이전트가 겪는 문제 - 수백 개의 Gradle 모듈과 방대한 코드 때문에 검색 한 번에도 지나치게 많은 결과가 반환됩니다. - 검색 결과가 에이전트 컨텍스트에 포함되면서 토큰과 비용이 빠르게 증가합니다. - 텍스트 검색만으로는 다음과 같은 의미론적 질문에 정확히 답하기 어렵습니다. - 특정 심볼의 선언 위치 - 심볼의 실제 참조 위치 - IDE가 판단하는 사용되지 않는 코드나 경고 - 의존성 내부 심볼의 위치 - 관련 없는 결과를 바탕으로 에이전트가 반복 검색과 재시도를 수행하면서 비효율이 커집니다. - 따라서 Android CLI를 그대로 적용하기보다는 래퍼, 스킬, 프롬프트를 통한 보완이 필요합니다. ## 문서 검색을 Android CLI로 전환 - Android CLI는 빌드·배포, SDK 관리, 환경 진단, 공식 문서 검색, Android Studio 연동 등을 제공합니다. - 첫 적용 대상은 Android, Jetpack Compose, AndroidX, Firebase 등의 공식 문서 검색이었습니다. - 모델의 사전 학습 지식은 최신 API 변경을 반영하지 못할 수 있어 잘못된 시그니처를 생성하는 환각이 발생할 수 있습니다. - 최신 Android Knowledge Base를 직접 참조하면 문서의 권위와 최신성을 확보할 수 있습니다. - 기존에는 Google Cloud Knowledge MCP 서버를 사용했지만 다음 운영 부담이 있었습니다. - 개발자별 Google Cloud API 인증 설정 - 인증 프록시 운영 - API 할당량 제한 대응 로직 유지 - Android CLI의 `docs` 명령은 다음 두 단계로 사용됩니다. - `docs search`: 키워드로 공식 문서 검색 - `docs fetch`: 검색 결과의 KB URL로 문서 본문 조회 - 이 기능은 `get-android-dev-knowledge` 스킬로 에이전트에 제공됩니다. - 기존 MCP 방식과 비교해 인증, 프록시, 할당량 처리 인프라를 제거하고 더 적은 토큰으로 최신 문서를 참조할 수 있습니다. ## CLI 바이너리를 저장소에 번들링한 이유 LINE 팀은 전역 설치된 `android` 명령 대신 `.agents/tools/android-cli/android`처럼 저장소 내부의 고정 경로에 바이너리를 포함했습니다. ### 환경 파편화 방지 - 개발자마다 CLI 버전, 설치 위치, 운영체제가 달라지는 문제를 줄입니다. - 저장소를 클론하면 동일한 버전을 사용할 수 있습니다. - 개발자 장비뿐 아니라 CI와 AI 에이전트 실행 호스트에서도 동일한 환경을 보장합니다. ### 보안 정책과 래퍼 적용 - Android CLI는 호출 과정에서 일부 데이터를 수집할 수 있습니다. - 이를 막으려면 호출마다 `--no-metrics` 인자를 지정해야 합니다. - 에이전트가 해당 인자를 누락할 수 있으므로 모든 호출을 통과시키는 래퍼에서 강제하는 방식이 안전합니다. - 래퍼가 실제 바이너리를 안정적으로 찾으려면 바이너리 위치가 고정되어 있어야 하므로 저장소 번들링이 유리합니다. - 대규모 저장소에 이미 `git-lfs`가 적용되어 있어 바이너리 포함 비용도 감당할 수 있었습니다. ## `--no-metrics` 관련 버그와 오류 출력 개선 - Android CLI 1.0 도입 과정에서 정보 수집 기능이 `--no-metrics` 처리 전에 초기화되는 버그가 발견되었습니다. - 이 때문에 메트릭 수집을 비활성화해도 `~/.android/cli`에 쓰기를 시도할 수 있습니다. - 샌드박스나 파일 시스템 권한으로 쓰기가 차단되면 여러 페이지의 Java 스택 트레이스가 출력됩니다. - 장황한 스택 트레이스는 에이전트 컨텍스트를 불필요하게 차지하고 문제 해결도 어렵게 만듭니다. - 래퍼는 CLI 실행 전에 다음을 수행합니다. - `~/.android/cli` 디렉터리 생성 시도 - 임시 파일을 만들어 쓰기 권한 확인 - 쓰기가 막히면 한 줄짜리 파싱 가능한 오류 출력 - 에이전트는 이제 긴 예외 대신 “쓰기 권한을 부여한 뒤 재시도하라”는 원인과 조치를 직접 전달받습니다. - 반복적으로 발생하는 오류를 에이전트가 처리하기 쉬운 구조화된 메시지로 변환하는 방식은 이후 Android Studio 연동에도 적용됩니다. ## Android Studio 연동의 의미론적 기능 Android CLI 1.0에서는 실행 중인 Android Studio와 연결해 IDE 수준의 분석을 명령줄에서 수행할 수 있게 되었습니다. - `studio check` - Android Studio 실행 여부를 확인합니다. - 대상 프로젝트가 열려 있는지 확인합니다. - 프로젝트 인덱싱이 완료되었는지 확인합니다. - 다른 Studio 기능을 사용하기 위한 전제 조건입니다. - `studio analyze-file` - 빌드하지 않고 단일 파일에 IDE 인스펙션을 적용합니다. - 에러와 경고를 반환합니다. - `is never used`처럼 단순한 `grep`으로 파악하기 어려운 의미론적 문제도 찾을 수 있습니다. - `studio find-declaration` - 심볼의 선언 위치를 찾습니다. - 프로젝트 코드뿐 아니라 `.aar`, `.jar` 의존성 내부도 검색합니다. - `studio find-usages` - 특정 심볼이 사용된 위치를 찾습니다. - `studio render-compose-preview` - `@Preview`가 적용된 Jetpack Compose 화면을 PNG 이미지로 렌더링합니다. ## CLI를 래퍼와 스킬로 감싼 설계 - Android Studio 기능도 CLI를 에이전트에 직접 노출하지 않고 얇은 래퍼와 스킬을 통해 제공합니다. - 가장 먼저 `studio-check` 스킬을 만들었습니다. - 에이전트가 CLI의 복잡한 입출력과 환경 전제 조건을 직접 처리하지 않도록 하는 것이 목적입니다. - 래퍼는 권한 확인, 실행 환경 검증, 오류 메시지 정규화 같은 공통 처리를 담당합니다. - 스킬은 에이전트가 언제 어떤 기능을 사용해야 하는지 안내하는 고수준 인터페이스 역할을 합니다. 실무적으로는 대규모 저장소에서 Android CLI를 전역 도구로 배포하기보다, 버전을 고정한 바이너리를 저장소에 포함하고 모든 호출을 래퍼로 통제하는 방식을 추천할 수 있습니다. 특히 검색 결과를 무작정 늘리는 대신 문서 검색, 심볼 탐색, IDE 분석처럼 목적에 맞는 의미론적 명령을 스킬로 제공하면 토큰 낭비와 에이전트의 반복 작업을 크게 줄일 수 있습니다.

안드로이드 VPAT 여정 (새 탭에서 열림)

Slack은 2024년 대규모 UI 개편 이후 제3자 VPAT 평가를 진행하며 Android 전반의 접근성 문제를 발견했다. 단순한 색상 대비·이미지 라벨 문제뿐 아니라 오류 안내, 제목 구조, 입력 필드 라벨, 목록 개수, 드래그 앤 드롭 등 반복적인 문제가 확인되었고, 이를 공통 컴포넌트와 TalkBack 지원 개선으로 해결했다. 특히 시각적 UI를 추가하는 데 그치지 않고, 스크린 리더 사용자가 동일한 기능을 수행할 수 있도록 의미 구조와 대체 조작 방식을 제공하는 데 중점을 두었다. ## VPAT 평가와 Android 접근성 문제의 분류 - VPAT(Voluntary Product Accessibility Template)는 제품이 접근성 표준을 얼마나 충족하는지 설명해 고객의 구매 판단을 돕는 문서다. - Slack은 IA4 UI 개편 이후 2024년에 외부 접근성 전문 업체를 통해 VPAT 평가를 실시했다. - Android, iOS, 데스크톱에서 문제가 발견되었으며, Android에서는 다음과 같은 유형이 주요 이슈로 나타났다. - 오류 메시지가 스크린 리더에 전달되지 않음 - 제목이 제목 요소로 식별되지 않음 - 입력 필드에 영구적인 접근성 라벨이 없음 - 목록 항목 수가 잘못 안내됨 - 워크스페이스 순서 변경 기능이 드래그 앤 드롭에 의존함 - 취소선 정보가 스크린 리더에 전달되지 않음 - 오류를 색상만으로 표시함 - 키보드 탐색과 포커스 문제는 다수 보고되었지만, Android의 대형 화면 지원이 아직 제한적이어서 후속 과제로 남겼다. ## 오류 메시지의 스크린 리더 전달 - 잘못된 값을 입력한 뒤 “Next” 또는 제출을 누르면 오류가 화면에 표시되지만, TalkBack에는 오류 상태와 원인이 전달되지 않았다. - 오류 표시 방식은 크게 두 가지였다. - `OutlinedTextField` 바로 아래에 오류 메시지를 표시 - `SKBanner`를 이용해 오류 배너를 표시 - 두 경우 모두 TalkBack이 오류를 자동으로 읽지 않아 사용자가 화면을 직접 탐색해야 했다. - 해결 방법: - `OutlinedTextField`를 수정해 입력 필드에 포커스가 갔을 때 오류 상태와 메시지를 안내하도록 변경 - 오류 유형의 `SKBanner`도 오류 발생 시 스크린 리더가 내용을 읽도록 수정 ## 제목 구조와 페이지 탐색 개선 - 제목이 시맨틱하게 식별되지 않으면 스크린 리더 사용자가 페이지의 구조를 빠르게 파악하거나 제목 단위로 이동하기 어렵다. - Preferences와 같은 목록 내부에서 누락된 제목 요소를 찾아 수정했다. - 외부 업체는 상단 앱 바의 제목도 heading으로 지정할 것을 제안했지만, 다른 Android 앱과 표준 동작을 비교한 결과 일관된 Android 관행이 아니라고 판단해 해당 티켓은 종료했다. ## 입력 필드의 영구 라벨 문제 - 일부 입력 필드는 placeholder만 라벨로 사용했다. - 사용자가 텍스트를 입력하면 placeholder가 사라지므로, 인지적 어려움이 있는 사용자는 필드의 목적을 잊을 수 있다. - 메시지 입력 영역(AMI)은 공간 제약 때문에 이상적인 해결책을 적용하지 못했다. - 검색 필드에는 돋보기 아이콘을 추가했다. - 입력 전후에도 해당 필드가 검색용이라는 시각적 단서를 제공한다. - 작은 디자인 변경으로 입력 필드의 목적을 더 명확하게 만들었다. - 이 문제는 접근성 개선이 반드시 복잡한 기술적 변경을 요구하지 않으며, 적절한 시각적·의미적 단서만으로도 사용성을 크게 높일 수 있음을 보여준다. ## 목록 항목 수를 정확히 안내 - TalkBack의 “항상 목록 항목 수 말하기” 설정이 켜져 있으면 목록의 전체 항목 수가 안내된다. - Slack의 구형 Slack Kit(SK) Bottom sheet에서는 장식용 divider까지 목록 항목으로 계산됐다. - 실제 행이 5개이고 divider가 2개면 TalkBack이 “7개 항목이 있는 목록”이라고 안내했다. - 해결을 위해 `SKListAdapter`에 새로운 `SKListAccessibilityDelegate`를 도입했다. - 이 delegate는 접근성용 `CollectionInfo`를 덮어써 실제 의미 있는 목록 항목 수만 전달한다. ## 드래그 앤 드롭을 대체하는 워크스페이스 이동 방식 - 워크스페이스 전환기에서는 워크스페이스를 선택한 뒤 드래그해 순서를 변경해야 했다. - 손의 움직임이나 정교한 조작이 어려운 사용자는 이 기능을 수행하기 힘들거나 사용할 수 없었다. - 해결 방법: - 워크스페이스 전환기에 `Edit` 모드를 추가했다. - 편집 모드에서는 각 행에 6점 모양의 드래그 핸들을 표시해 이동 가능한 요소임을 명확히 했다. - TalkBack 사용자를 위해 사용자 지정 접근성 동작인 “앞으로 이동(Move before)”과 “뒤로 이동(Move after)”을 추가했다. - TalkBack 컨텍스트 메뉴의 세 손가락 탭 또는 `L`, `r` 제스처로 항목을 이동할 수 있게 했다. - 정렬이 끝나면 우측 상단의 “Done” 버튼을 눌러 편집 모드를 종료한다. - 시각적 드래그 UI와 스크린 리더용 명령형 조작을 함께 제공해 동일한 기능에 여러 접근 경로를 마련했다. ## 남은 접근성 개선 과제 - 취소선 정보가 스크린 리더에 전달되지 않는 문제와 오류를 색상만으로 표시하는 문제도 주요 이슈로 분류되었다. - 키보드 탐색과 포커스는 Android 태블릿 등 대형 폼 팩터에서 특히 중요하지만, Slack Android의 대형 화면 지원이 충분하지 않아 추가 검토 과제로 남았다. - 접근성 문제는 개별 화면의 수정만으로 끝나지 않고 공통 UI 컴포넌트와 접근성 메타데이터 처리 계층까지 개선해야 반복을 줄일 수 있다. 접근성을 개선할 때는 시각적 표시만 추가하지 말고, TalkBack이 오류·제목·목록 구조·상태 변화를 정확히 인식하는지 함께 검증해야 한다. 또한 드래그처럼 정밀한 동작이 필요한 기능에는 접근성 사용자 지정 동작이나 명시적인 편집 모드를 제공하는 것이 효과적이다.