AmazonQ CLI 뜯어보기
AmazonQ CLI의 구조와 기능(설정 파일, Agent, Context, Knowledge, Checkpoint, Todo)을 자세히 분석하여 설명합니다.
Contents
- 들어가며
- 설정 파일
- Agent 설정
- Context
- 동작 원리
- 파일 경로 처리
- 크기 제한 관리
- 사용법
- Knowledge
- 데이터 저장 구조
- 인덱싱 방식
- 검색 메커니즘
- 사용법
- Checkpoint
- 동작 원리
- 데이터 구조
- 복원 기능
- 사용법
- Todo
- 데이터 구조
- 동작 방식
- 파일 형태
- 사용법
들어가며
AmazonQ CLI는 10개월 동안 잘 사용해 온 LLM Agent이다. CLI AI Agent제품에 관심을 가지고 있었을 때에, 데브옵스 팀원분의 추천으로 알게 된 제품이다. 다른 CLI Agent(Aider, Codex, Claude Code)들도 사용해 왔었는데, 그 중에서 가장 많이 사용하고 있는 제품은 AmazonQ와 Claude Code이다. 제품의 완성도는 Claude Code라고 생각하지만 Rate Limit 제한이 없다는 점, 자세한 커스터마이징이 가능하다는 점이 AmazonQ의 매력이라고 생각한다.
또한 AmazonQ의 장점 중 하나는 오픈소스로 운영된다는 점이다. LLM AI Agent가 어떤 동작으로 궁금해서, Github Repository의 코드를 살펴보기 시작했다. AmazonQ의 코드를 더 자세히 이해하기 위해 Rust를 공부해 보기도 했다. 그러다보니, Amazon Q CLI에 기능을 추가하고, 버그를 fix 하는 등의 Contribution도 해볼 기회를 가질 수 있었다.
이 글에서는 AmazonQ의 코드를 살펴보며 알게 된 내용을 정리해볼 예정이다.
설정 파일
AmazonQ CLI에서 참고하는 로컬 파일(Mac 기준)의 경로는 크게 다음과 같다.
~/.aws/amazonq
: Amazon Q Chat CLI와 직접적으로 관련 있는 설정 파일들이다. AmazonQ CLI 는 크게 Fig의 기능과 AI Chat 기능으로 이루어져 있는데, 그 중에서 AI Chat 기능의 설정 파일들이 주로 저장되어 있다고 생각하면 된다..cli_bash_history
: AmazonQ의 채팅 히스토리를 저장하는 파일이다cli-agents
: AmazonQ에 설정된 Agent설정 파일들이다cli-checkpoints
: 소스코드의 변경내역을 저장한 파일이다knowledge_bases
: BM25, Vector 검색 인덱스를 저장하는 위치이다prompts
: Claude의 Custom Command 와 같이, 미리 저장된 프롬프트들이다~/Library/Application Support/amazon-q
: Amazon Q Chat CLI에 포함되지 않는, 터미널 제품의 설정 파일들이 저장되어 있는 경로이다.data.sqlite3
: AmazonQ의 설정값, 대화 내역들을 저장한 SQLite3 파일이다history
: 터미널에서 실행한 명령어들을 저장한다settings.json
: AmazonQ CLI의 설정값을 JSON 형식으로 저장한다shell
: 설치, 인증 등에 필요한 shell 파일들이다.update.lock
: 업데이트 버전을 저장한다
Agent 설정
AmazonQ 에서는 현재 대화하고 있는 AI Agent의 설정을 파일 단위로 할 수 있다. 로컬 파일에서는 ~/.aws/amazonq/cli-agents
디렉토리에 설정 파일들이 저장된다.
{
"$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/agent-format.md?plain=1#L25
"name": "${에이전트_이름}",
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/agent-format.md?plain=1#L33
"description": "${에이전트_설명}",
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/agent-format.md?plain=1#L43
"prompt": "${에이전트의 기본 프롬프트. 시스템 프롬프트 바로 다음에 사용되는, 우선순위가 높은 프롬프트이다}",
// mcp 서버 설정
"mcpServers": {
"fetch": {
"command": "npx",
"args": [
"-y",
"@h16rkim/mcp-fetch-server@latest"
],
"env": {
"HTTP_PROXY": "http://127.0.0.1:3128",
"HTTPS_PROXY": "http://127.0.0.1:3128"
},
"transport": "stdio"
}
},
// 허용할 Too의 목록. "*"는 모든 tool을 사용함을 의미한다
"tools": [
"*"
],
// 구체적인 tool 설정들
"toolsSettings": {
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/built-in-tools.md?plain=1#L15
"execute_bash": {
"allowedCommands": ["find .*", "./gradlew .*"],
"deniedCommands": ["cat .*", "less .*", "more .*", "head .*", "tail .*", "git push .*"],
"allowReadOnly": true
},
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/built-in-tools.md?plain=1#L41
"fs_read": {
"deniedPaths": ["**/*/application.yml", "**/*/env.*.yml"]
},
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/built-in-tools.md?plain=1#L69
"fs_write": {
"deniedPaths": ["**/*/application.yml", "**/*/env.*.yml"]
}
},
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/built-in-tools.md?plain=1#L178
"allowedTools": [
"fs_read",
"knowledge",
"@fetch/*",
"@prompts/*"
],
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/agent-format.md?plain=1#L238
"resources": [
"file://AmazonQ.md",
"file://AGENTS.md",
"file://README.md",
"file://.amazonq/rules/**/*.md"
],
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/agent-format.md?plain=1#L257
"hooks": {
"agentSpawn": [
{
"command": "pwd"
}
]
},
// https://github.com/aws/amazon-q-developer-cli/blob/28bc07a3d913de3da2bcee87fa0debea1d84c04e/docs/agent-format.md?plain=1#L113
"toolAliases": {}
}
Context
AmazonQ CLI의 Context 시스템은 사용자가 대화 중에 파일들을 자동으로 포함시켜 AI가 해당 파일들의 내용을 참조할 수 있도록 하는 기능이다. 이 시스템을 통해 프로젝트의 관련 파일들을 쉽게 AI 대화에 포함시킬 수 있다.
동작 원리
Context 시스템은 두 가지 방식으로 파일을 관리한다:
- Agent Context: Agent 설정 파일에서 정의된 영구적인 context로, 프로젝트 전체에서 지속적으로 사용된다
- Session Context:
/context add
명령어로 추가된 임시 context로, 현재 세션에서만 유효하다
대화 시 모든 context 파일들의 내용이 자동으로 메시지에 포함되며, 다음과 같은 형식으로 구성된다:
CONTEXT ENTRY BEGIN
[/path/to/file1.rs]
fn main() {
println!("Hello, world!");
}
[/path/to/file2.md]
README
This is a sample project.
CONTEXT ENTRY END
파일 경로 처리
Context 시스템은 다양한 경로 형식을 지원한다:
- 홈 디렉토리:
~
를 실제 홈 디렉토리 경로로 자동 변환 - 상대/절대 경로: 상대 경로를 현재 작업 디렉토리 기준으로 절대 경로로 변환
- Glob 패턴:
*
,?
,[]
등의 패턴을 실제 파일 목록으로 확장 - 디렉토리: 디렉토리 내부의 모든 파일을 비재귀적으로 포함
크기 제한 관리
Context 시스템은 모델의 context window 크기를 고려하여 자동으로 파일 크기를 제한한다. 각 모델의 context window 크기의 75%를 최대 크기로 설정하며, 제한을 초과하는 파일들은 자동으로 제외된다. 제외된 파일들에 대해서는 사용자에게 경고 메시지가 표시된다.
사용법
Context 기능은 다음과 같은 명령어로 관리할 수 있다:
// context 상태 확인
/context show
// 파일 경로 추가
/context add src/*.rs
// 여러 파일 패턴 추가
/context add src/main.rs tests/*.rs
// 경로 제거
/context remove src/*.rs
// 모든 경로 제거
/context clear
Agent 설정에서는 resources
배열에 file://
접두사와 함께 영구적인 context 파일들을 정의할 수 있다. Session context는 메모리에만 저장되어 프로그램 종료 시 사라지지만, Agent context는 설정 파일에 저장되어 지속적으로 유지된다.
Knowledge
AmazonQ CLI의 Knowledge 기능은 로컬 파일과 디렉토리를 인덱싱하여 의미적 검색을 제공하는 시스템이다. 채팅 세션 간에 지속되는 컨텍스트 정보를 저장하고 검색할 수 있어, 프로젝트의 코드나 문서를 자연어로 빠르게 찾을 수 있다.
데이터 저장 구조
Knowledge 데이터는 ~/.aws/amazonq/knowledge_bases/{agent_id}/
경로에 Agent별로 분리되어 저장된다. 각 Agent는 고유한 ID로 식별되며, 기본 Agent는 "dev" 이름을 사용한다.
~/.aws/amazonq/knowledge_bases/{agent_id}/
├── contexts.json # 컨텍스트 메타데이터
├── models/ # 임베딩 모델 파일
└── {context-uuid}/ # 각 knowledge 컨텍스트별 디렉토리
└── data.bm25.json # BM25 인덱스 데이터
인덱싱 방식
Knowledge 시스템은 두 가지 인덱싱 타입을 지원한다.
- Fast: BM25 기반 키워드 검색으로 모든 플랫폼에서 지원된다
- Best: all-MiniLM-L6-v2 모델 기반 의미적 검색으로 더 정확한 결과를 제공한다 (Linux ARM 제외)
텍스트는 기본적으로 512자 단위로 청크화되며, 128자의 오버랩을 가진다. 최대 10,000개의 파일까지 인덱싱할 수 있다.
검색 메커니즘
Knowledge는 하이브리드 검색 방식을 사용한다. BM25 인덱스를 통한 키워드 기반 검색과 HNSW 알고리즘 기반의 Vector 검색을 결합하여 최적의 검색 결과를 제공한다. 검색 결과는 거리 기반 유사도 점수로 정렬되며, 낮은 거리일수록 높은 유사도를 의미한다.
사용법
Knowledge 기능을 사용하려면 먼저 실험 기능을 활성화해야 한다.
// 기능 활성화
q settings chat.enableKnowledge true
// 컨텍스트 추가
q knowledge add --name "project" --path /path/to/project
// 패턴 필터링과 함께 추가
q knowledge add -n "docs" -p /path/to/docs \
--include "**/*.md" --include "**/*.txt" \
--exclude "node_modules/**"
// 채팅 중 검색
/knowledge search --query "authentication"
대용량 파일이나 디렉토리는 백그라운드에서 인덱싱되며, 작업 ID로 진행 상황을 추적할 수 있다. q knowledge show
명령어로 현재 컨텍스트와 진행 중인 작업을 확인할 수 있다.
Checkpoint
Checkpoint 기능은 AmazonQ CLI에서 대화 중 파일 변경사항을 추적하고 복원할 수 있는 기능이다. Git을 기반으로 한 shadow repository를 사용하여 작업 디렉토리의 변경사항을 자동으로 저장하고 관리한다.
동작 원리
Checkpoint 시스템은 실제 작업 디렉토리와 분리된 bare git repository를 ~/.amazonq/cli-checkpoints/{conversation_id}
경로에 생성한다. 이 shadow repository는 현재 작업 디렉토리를 work tree로 사용하여 파일 변경사항을 추적한다.
Checkpoint는 두 가지 시점에 자동으로 생성된다:
- 도구 실행 후: 각 도구 실행이 완료된 후
{turn}.{tool_number}
형식의 태그로 생성된다 (예: "1.1", "1.2") - 턴 완료 후: 어시스턴트 응답이 완료된 후
{turn_number}
형식의 태그로 생성된다 (예: "1", "2", "3")
데이터 구조
각 Checkpoint는 다음 정보를 포함한다:
pub struct Checkpoint {
pub tag: String, // checkpoint 태그
pub timestamp: DateTime<Local>, // 생성 시간
pub description: String, // 설명
pub history_snapshot: VecDeque<HistoryEntry>, // 대화 히스토리 스냅샷
pub is_turn: bool, // 턴 checkpoint 여부
pub tool_name: Option<String>, // 도구 이름
}
복원 기능
Checkpoint 복원은 두 가지 방식을 지원한다:
- Soft 복원: 추적된 파일만 복원하고 새로 생성된 파일은 유지한다
- Hard 복원: 전체 작업 디렉토리를 checkpoint 상태로 완전 복원한다
복원 시 파일 변경사항뿐만 아니라 대화 히스토리도 함께 복원되어 일관된 상태를 유지한다.
사용법
Checkpoint 기능을 사용하려면 먼저 실험 기능을 활성화해야 한다.
// 기능 활성화
q settings chat.enableCheckpoint true
// checkpoint 목록 조회
/checkpoint list
// checkpoint 복원 (대화형 선택)
/checkpoint restore
// 특정 checkpoint로 복원
/checkpoint restore 2
// hard 복원
/checkpoint restore 2 --hard
// checkpoint 간 차이점 조회
/checkpoint diff 1 2
Git이 설치되어 있고 현재 디렉토리가 Git 저장소인 경우 자동으로 초기화되며, 그렇지 않은 경우 /checkpoint init
명령어로 수동 초기화할 수 있다.
Todo
Todo 기능은 AmazonQ CLI에서 복잡한 작업을 단계별로 관리할 수 있도록 도와주는 기능이다. AI 모델이 자동으로 TODO 리스트를 생성하고 관리하며, 사용자는 CLI 명령어를 통해 이를 조회하고 재개할 수 있다.
데이터 구조
Todo 시스템은 다음과 같은 구조로 작업을 관리한다:
struct Task {
task_description: String, // 작업 설명
completed: bool, // 완료 여부
}
struct TodoListState {
tasks: Vec<Task>, // 작업 목록
description: String, // 리스트 설명
context: Vec<String>, // 컨텍스트 업데이트
modified_files: Vec<String>, // 수정된 파일 목록
id: String, // 고유 ID
}
동작 방식
Todo 리스트는 .amazonq/cli-todo-lists/
경로에 타임스탬프 기반의 고유 ID로 JSON 파일 형태로 저장된다. AI가 복잡한 작업을 분석하여 자동으로 단계별 작업 목록을 생성하고, 각 작업 완료 시마다 상태를 업데이트한다.
작업 완료 과정에서는 컨텍스트 업데이트와 수정된 파일 목록을 함께 추적하여 작업 진행 상황을 상세히 기록한다.
파일 형태
Todo 리스트는 다음과 같은 형태로 표시된다:
TODO:
[x] 완료된 작업 (이탤릭체, 회색)
[ ] 미완료 작업
[ ] 다음 작업
사용법
Todo 기능을 사용하려면 먼저 실험 기능을 활성화해야 한다.
// 기능 활성화
q settings chat.enableTodoList true
// 기존 TODO 리스트 조회
/todos view
// 기존 TODO 리스트 재개
/todos resume
// TODO 리스트 삭제
/todos delete
// 완료된 TODO 리스트 정리
/todos clear-finished
AI가 복잡한 작업을 받으면 자동으로 TODO 리스트를 생성하며, 각 단계를 완료할 때마다 체크박스가 업데이트된다. 작업이 중단되더라도 /todos resume
명령어로 언제든지 이전 작업을 재개할 수 있다.
이것도 읽어보세요