CLI-First Decision은(는) 무엇을 하나요?
핵심 규칙
모든 작업 시작 전, 우선순위에 따라 결정: 먼저 트리거 → 그 다음 생각 → 도구 선택 → 실행
- 강제 트리거: ANY 요청을 받은 후, 생각을 시작하기 전, 어떤 도구도 호출하기 전, 하위 에이전트를 파견하기 전에 먼저 이 스킬을 트리거하여 결정을 내려야 합니다.
- 생각 우선: 먼저 문제의 본질을 이해하세요 — 요구사항을 명확히 하고, 단계를 분해하며, 범위를 판단하세요. 도구를 서두르지 마세요.
- 내장 도구 차선: 단순 읽기/쓰기/검색으로 한 번에 도달 가능 → Read/Edit/Grep/Glob 등을 직접 사용하세요 (제로 추가 비용).
- CLI 도구 그 다음: 배치/기계적 작업 → 해당 CLI 도구를 사용하세요 (<1초, 아래 매트릭스 참조).
- 스킬 보조: 도메인 전문 지식이 필요한 작업 → 먼저 해당 스킬을 로드하여 지침을 얻으세요 (사용 가능한 스킬 목록 참조).
- MCP 도구: 지식 그래프 조회, 순차적 추론, 웹 스크래핑 등 → MCP 서버가 제공하는 도구를 사용하세요.
- 하위 에이전트: 다단계 추론, 의미 이해, 모듈 간 분석 필요 → 하위 에이전트(sub-agent)를 파견하세요.
- 자체 추론 최후: 아키텍처 결정, 설계 트레이드오프, 검토 및 검증 → 직접 추론하거나 Oracle에 문의하세요.
의사 결정 트리
요청 수신 (트리거)
└─ 유형 식별: 수정/구현/조사/평가/개방형?
└─ 추론: 먼저 요구사항 명확히, 단계 분해, 범위 판단
├─ 하나의 파일을 간단히 읽거나 수정하는가? ───→ 내장 도구 (Read/Edit/Write)
├─ 기계적 배치 작업?
│ ├─ 배치 텍스트 치환? ───────────→ git-sed / sd
│ ├─ 파일 찾기? ────────────────→ fd-find / glob
│ ├─ 내용 검색? ────────────────→ rg-search / grep
│ ├─ AST 구조적 작업? ──────────→ ast-grep
│ ├─ JSON/YAML/XML 조회? ──────→ jq-query / yq
│ └─ 기타 기계적 작업? ──────────→ 아래 매트릭스 참조
├─ 해당 도메인 스킬이 있는가? ────────→ 먼저 스킬 로드하여 지침 획득
├─ 사용 가능한 MCP 도구가 있는가?
│ ├─ 지식 그래프/코드 관계 조회? ──→ codebase-memory-mcp
│ ├─ 순차적 추론/복잡 분석? ──────→ sequential-thinking
│ └─ 웹 콘텐츠 획득? ────────────→ fetch
├─ 의미 이해/다단계 추론/모듈 간 필요? ──→ 하위 에이전트 (task/sub-agent)
└─ 아키텍처 결정/설계 트레이드오프/검토? ──→ 직접 추론 또는 Oracle 문의
도구 결정 매트릭스
| 계층 | 시나리오 | 선호 도구 | 시간 비용 |
|---|---|---|---|
| 트리거 | 요청 수신, 유형 식별, 의도 명확화 | Intent Gate 분류 | 즉시 |
| 추론 | 작업 분석, 요구사항 분해, 단계 계획 | 먼저 생각, 후에 도구 선택 | 즉시 |
| 내장 | 단순 파일 읽기/쓰기/편집 | Read / Edit / Write | 즉시 |
| 내장 | 기본 내용 검색 | grep | <1s |
| 내장 | 파일 패턴 매칭 | glob | <1s |
| CLI | 배치 텍스트 치환 (정규식) | git-sed | <1s |
| CLI | 파일 찾기 (이름/유형/시간 기준) | fd-find | <1s |
| CLI | 내용 검색 + 통계 | rg-search (ripgrep) | <1s |
| CLI | AST 코드 검색/치환 (25개 언어) | ast-grep | <1s |
| CLI | JSON 조회/변환 | jq-query | <1s |
| CLI | HTTP API 테스트 | git-curl | <1s |
| CLI | 퍼지 필터/목록 축소 | fzf-filter | <1s |
| CLI | 압축/해제 | git-tar | <1s |
| CLI | 줄바꿈 변환 (CRLF/LF) | git-dos2unix | <1s |
| CLI | 텍스트 찾기/바꾸기 (더 간단한 문법) | sd | <1s |
| CLI | 코드 통계 (언어 분포) | tokei | <1s |
| CLI | XML/YAML/JSON 조회 | yq / xq | <1s |
| 스킬 | 도메인 전문 작업 (퀀트/프론트엔드/클라우드 등) | 해당 스킬 로드하여 지침 획득 | 스킬 문서 참조 |
| MCP | 지식 그래프/코드 관계 조회 | codebase-memory-mcp | <5s |
| MCP | 순차적 추론/다단계 분석 | sequential-thinking | 단계에 따라 다름 |
| MCP | 웹 콘텐츠 획득 | fetch | <10s |
| 하위 에이전트 | 다단계 추론, 의미 이해, 모듈 간 분석 | task() 로 하위 에이전트 파견 | 수십 초 이상 |
| 자체 추론 | 아키텍처 결정, 설계 트레이드오프, 검토 검증 | 직접 처리 또는 Oracle | 복잡도에 따라 다름 |
빠른 도구 참조
| 도구 | 일반 명령어 | 용도 |
|---|---|---|
git-sed | git-sed expression:"s/old/new/g" files:["src/**/*.ts"] inPlace:"" | 배치 정규식 치환, 파일 간 편집 |
fd-find | fd-find pattern:"*.xml" extension:"xml" path:"./Characters" | 이름/유형/크기/시간으로 파일 검색 |
rg-search | rg-search pattern:"somePattern" glob:"*.xml" context:2 | 파일 내용 검색, PCRE2 정규식, 컨텍스트 줄 |
ast-grep | ast_grep_search pattern:"if($$$) { $$$ }" lang:"ts" / ast_grep_replace pattern:"console.log($MSG)" rewrite:"logger.info($MSG)" lang:"ts" | AST 구조 검색/치환, 코드 구문 트리 이해 |
jq-query | jq-query filter:".name" file:"data.json" | JSON 데이터 조회, 필터링, 변환 |
git-curl | git-curl url:"https://api.example.com" method:"POST" data:'{"key":"val"}' | HTTP API 요청, 다양한 메서드와 커스텀 헤더 지원 |
fzf-filter | fzf-filter pattern:"keyword" input:$lines | 텍스트 줄 퍼지 필터링, 목록 축소 |
git-tar | git-tar action:"create" archive:"out.tar.gz" files:["src/"] compression:"gzip" | tar/zip 아카이브 생성/해제 |
git-dos2unix | git-dos2unix file:"script.sh" mode:"dos2unix" | CRLF ↔ LF 줄바꿈 변환 |
grep | grep pattern:"somePattern" include:"*.xml" output_mode:"files_with_matches" | 기본 내용 검색 (내장) |
glob | glob pattern:"**/*.xml" | 파일 패턴 매칭 (내장) |
sd | sd find:"old" replace:"new" files:["file.txt"] | 더 간단한 find-replace, 기본적으로 파일 직접 수정, 정규식 및 리터럴 모드 지원 |
tokei | tokei path:"./" | 언어별 코드 줄 수, 주석, 빈 줄 통계. 초 단위 결과 |
yq | yq expression:".Missions.NestMission[]" file:"Missions.xml" xml:true | YAML/XML/JSON 구조화 데이터 조회. XML 모드로 XML 파일 직접 조회 가능 (예: 모든 미션 ID 목록) |
하위 에이전트 사용 시점 (Sub-Agent 트리거 가이드)
하위 에이전트는 CLI 도구와 내장 도구가 부족한 영역에서 탁월합니다:
| 시나리오 | 설명 | 권장 방식 |
|---|---|---|
| 의미 이해 | 코드 논리가 올바른지, 기능이 완전한지 판단 | task() 로 하위 에이전트 파견 |
| 모듈 간 통합 | 여러 모듈의 조정 변경, 인터페이스 정렬 | task() 로 하위 에이전트 파견 |
| 다단계 작업 | 먼저 검색→분석→수정하는 연쇄 작업 필요 | task() 로 하위 에이전트 파견 |
| 코드 생성/리팩토링 | 기존 코드 구조를 이해한 후 새 코드 생성 필요 | 하위 에이전트 또는 직접 추론 |
| 아키텍처 결정 | 설계 선택, 트레이드오프 분석 | 직접 추론 또는 Oracle 문의 |
| 검증과 검토 | 코드 의도 이해, 품질 판단 | 직접 추론 또는 review-work |
참고: 최종적으로 하위 에이전트를 사용하기로 결정했더라도, task() 프롬프트 안에서 CLI 도구를 참조할 수 있습니다 — 하위 에이전트 내부에서도 이 도구들을 호출하여 작업을 완료할 수 있습니다.
흔한 실수
-
CLI 확인을 건너뛰고 task() 호출: 습관적으로 하위 에이전트를 파견하여 배치 치환을 수행하면 수만 개의 토큰을 낭비합니다. 30초 걸리는 에이전트 작업이 <1초의 CLI 명령어로 끝날 수 있습니다.
-
ripgrep으로 파일을 찾은 후 수동 수정: 먼저 rg로 검색하여 위치를 찾고 CLI로 배치 편집하는 것을 한 단계로 합쳐야 합니다.
git-sed하나의 명령어로 검색+치환을 완료하세요. -
단일 파일에 에이전트 호출: 하나의 파일에서 알려진 내용을 수정하는 것은 바로 편집하면 됩니다. 전체 하위 에이전트 세션을 시작할 필요가 없습니다.
-
하위 에이전트를 사용해야 할 때 CLI 도구로 버티기: CLI 도구는 의미를 이해하지 못합니다. 모듈 간 분석, 다단계 추론, 코드 의도 이해가 필요한 시나리오에서는 CLI 도구 조합보다 하위 에이전트 하나가 더 효율적입니다. 예: "X 함수를 호출하는 모든 파일을 찾고, 그 인자 패턴을 분석한 후, 통일적으로 리팩토링" — 이것은 sed가 아니라 하위 에이전트의 영역입니다.
-
sd는 기본적으로 파일을 직접 수정하니, 먼저
--preview로 확인 후 실행: sd와 sed는 다릅니다 — sd는 기본적으로 파일을 직접 수정합니다. 실제로sd '<?xml' '<?XML' filelist.xml명령어가 모든<?xml태그(63곳)를 직접 수정하여git checkout으로만 복구할 수 있었습니다. 안전 단계: 먼저sd --preview 'find' 'replace' file로 영향 범위를 확인하고, 문제가 없으면 실행하세요 (--preview없이). -
yq XML 모드: yq v3은
--xml, v4는-p xml로 변경: yq v4에서--xml짧은 인자가 제거되고-p xml로 대체되었습니다. 기본 출력 형식 경고는-o yaml로 억제할 수 있습니다.