28. AI 코딩 에이전트 기본 활용법

이 문서는 AI 코딩 에이전트 두 가지(터미널형 Claude Code, 편집기형 Google Antigravity)를 설치하고, 응답 태도를 정한 뒤, 프로젝트를 분석시키고 코드를 고치게 하는 기본 사용 과정을 다룬다. Node.js가 설치된 컴퓨터와 연습용 프로젝트 폴더 하나만 있으면 시작할 수 있다. 다 따라 하면 에이전트 설치·프로젝트 컨텍스트 파일·에이전트에게 시킨 첫 코드 수정 결과가 남는다.

1 – 에이전트 이해와 설치

코딩 에이전트는 터미널에서 프로젝트 폴더 안의 파일을 직접 읽고·수정하고·명령을 실행하는 AI 도구다(정의). 채팅창에 코드를 복사해 붙여 넣는 방식과 달리, 에이전트는 폴더 전체를 스스로 탐색해 어떤 파일을 고쳐야 하는지 찾고 수정까지 실행한다(원인·동작). 이는 코드 조각을 들고 가서 상담만 받는 것과, 작업자가 내 작업실에 직접 들어와 도구를 들고 일하는 것의 차이와 같다(비유) — 작업실에 들어온 작업자는 재료가 어디 있는지 스스로 찾아 쓰므로, 일일이 가져다줄 필요가 없다.

1.1 – 작업 환경 준비

1. 터미널을 연다. Windows는 시작 메뉴에서 “PowerShell”을 검색해 실행하고, macOS는 ⌘+Space 입력 후 “터미널”을 검색해 실행한다.
2. Node.js가 설치돼 있는지 확인한다. 터미널에 node -v를 입력하고 Enter를 누른다.
3. v20.0.0 같은 버전 번호가 나오면 설치돼 있는 것이다. “command not found”가 나오면 nodejs.org에서 LTS 버전을 내려받아 설치한 뒤 터미널을 새로 연다.
4. 연습용 프로젝트 폴더를 만들고 그 폴더로 이동한다.

mkdir agent-practice
cd agent-practice

1.2 – Claude Code 설치와 로그인

https://code.claude.com/docs/en/quickstart#step-1-install-claude-code

1. 터미널에 아래 명령어를 입력하고 Enter를 누른다.

npm install -g @anthropic-ai/claude-code

1. 설치가 끝나면 claude를 입력하고 Enter를 누른다.
2. 처음 실행하면 브라우저가 열리며 로그인 화면이 나타난다. Anthropic 계정으로 로그인하고 [Authorize]를 클릭한다.
3. 터미널로 돌아오면 입력 프롬프트가 뜬다. 이 상태가 에이전트와 대화할 수 있는 세션이다.

1.3 – Google Antigravity 설치와 로그인

두 번째 에이전트로 Google Antigravity를 설치한다. Antigravity는 코드 편집기 안에 에이전트가 내장된 구글의 에이전트 중심 개발 도구다(정의). Claude Code가 터미널에서 대화하는 방식이라면, Antigravity는 편집기 화면에서 코드를 보면서 에이전트에게 일을 시키는 방식이다 — 도구의 모양은 달라도 에이전트를 부리는 방법(태도 정하기, 위계 있는 프롬프트, 작은 단위 요청)은 같다.

1. 브라우저 주소창에 antigravity.google을 입력하고 Enter를 누른다.
2. [Download] 버튼을 클릭하고 자기 운영체제(Windows/macOS)에 맞는 설치 파일을 내려받는다.
3. 내려받은 설치 파일을 실행해 설치를 마친다.
4. Antigravity를 실행하면 로그인 화면이 나온다. Google 계정으로 로그인한다.
5. [Open Folder]를 클릭해 “agent-practice” 폴더를 연다.
6. 화면의 에이전트 입력창에 지시를 적으면 Claude Code와 같은 방식으로 파일을 분석·수정한다.

이번 실습의 이후 단계는 Claude Code 기준으로 진행한다. 2장에서 익히는 흐름(태도 정하기 → 분석 → 컨텍스트 파일 → 작은 수정)은 Antigravity의 에이전트 입력창에서도 같은 프롬프트로 통한다.

1.4 – Codex CLI 설치

openAI의 Codex 를 설치한다.

^powershell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

로그인 한다

codex login

2 – 기본 사용 흐름

설치를 마쳤으니 에이전트를 실제로 부려 본다. 기본 흐름은 네 단계다: 응답 태도를 정하고 → 프로젝트를 분석시키고 → 컨텍스트 파일을 만들고 → 작은 수정을 시켜 결과를 확인한다.

2.1 – 응답 태도 정하기

일을 시키기 전에 에이전트가 어떤 태도로 응답할지부터 정한다. 태도 설정은 응답의 언어·설명 수준·진행 방식을 미리 지정하는 규칙이다(정의). 태도를 정하지 않으면 답변이 어떤 때는 영어로, 어떤 때는 장황하게, 어떤 때는 묻지도 않고 파일을 고치는 식으로 요청마다 달라진다(원인).

1. “agent-practice” 폴더에서 claude를 입력해 세션을 연다.
2. 입력 프롬프트에 아래 내용을 붙여 넣고 Enter를 누른다.

# 응답 태도 설정

이 세션에서 아래 태도를 유지한다.

## 태도 규칙
- 한국어로 답한다.
- 파일을 만들거나 고치기 전에 무엇을 할지 한 줄로 먼저 말한다.
- 요청이 애매하면 추측하지 말고 되묻는다.
- 설명은 처음 배우는 사람 기준으로 짧게 한다.

1. 에이전트가 규칙을 확인했다는 답을 돌려주면 설정된 것이다.

이렇게 정한 태도는 이 세션 동안만 유지된다. 세션을 닫으면 사라지므로, 2.3에서 만들 컨텍스트 파일에 같은 규칙을 옮겨 적어 매 세션 자동으로 적용되게 한다.

프롬프트는 위 예시처럼 마크다운 위계(# 제목, ## 소제목, 목록)로 적는다. 줄글로 길게 이어 붙인 프롬프트는 에이전트가 지시와 조건을 뒤섞어 읽기 쉽고, 위계가 있으면 요청 사항이 빠짐없이 전달된다.

2.2 – 프로젝트 분석 시키기

태도를 정했으니 첫 작업으로 프로젝트 분석을 시킨다.

1. 같은 세션에 아래 내용을 붙여 넣고 Enter를 누른다.

# 프로젝트 분석 요청

이 폴더의 구조와 파일을 분석한다.

## 정리할 것
1. 어떤 종류의 프로젝트인지
2. 폴더·파일 구조
3. 사용 중인 기술과 설정 파일

1. 에이전트가 폴더를 읽는 동안 진행 상황이 표시된다. 빈 폴더라면 “빈 폴더”라는 분석이 나온다 — 정상이다.

에이전트는 채팅 AI와 달리 답하기 전에 실제로 파일 목록을 조회한다. 분석 결과가 실제 폴더 내용과 일치하는지가 에이전트가 제대로 동작하는지 가리는 첫 확인 지점이다. 2.1에서 정한 태도 규칙대로 한국어로, 작업 전에 무엇을 할지 말하고 진행하는지도 함께 확인한다.

2.3 – 컨텍스트 파일 만들기

컨텍스트 파일은 에이전트가 세션을 시작할 때 가장 먼저 읽는 프로젝트 설명 파일이다(정의). 태도 규칙과 프로젝트 규칙을 여기에 적어 두면 매 세션 같은 설명을 반복하지 않아도 된다(원인). Claude Code는 “CLAUDE.md”라는 이름을 쓴다.

1. 세션에서 /init을 입력하고 Enter를 누른다.
2. 에이전트가 폴더를 분석해 “CLAUDE.md” 파일 초안을 만들고 저장 여부를 묻는다. Enter를 눌러 승인한다.
3. 2.1의 태도 규칙과 프로젝트 규칙을 함께 추가한다. 아래 내용을 입력하고 Enter를 누른다.

# 컨텍스트 파일 수정 요청

CLAUDE.md에 아래 규칙을 추가한다.

## 응답 태도
- 한국어로 답한다.
- 파일을 만들거나 고치기 전에 무엇을 할지 한 줄로 먼저 말한다.
- 요청이 애매하면 추측하지 말고 되묻는다.

## 코드 규칙
- 모든 HTML 파일은 시맨틱 태그(header, main, footer)를 사용한다.
- 파일명은 kebab-case로 짓는다.

1. 에이전트가 파일 수정 내용을 보여 주고 승인을 기다린다. 내용을 확인한 뒤 Enter를 눌러 승인한다.

이제 세션을 새로 열어도 이 태도와 규칙이 자동으로 적용된다.

2.4 – 첫 코드 작성과 수정 시키기

컨텍스트 파일에 적은 규칙이 실제로 지켜지는지 확인할 겸, 에이전트에게 첫 작업을 시킨다.

1. 아래 내용을 입력하고 Enter를 누른다.

# 페이지 작성 요청

자기소개 웹페이지를 한 장 만든다.

## 요구 사항
1. 파일명: my-profile.html
2. 이름, 취미 소개, 연락처 세 부분으로 구성한다.
3. CSS는 파일 안에 style 태그로 넣는다.

1. 에이전트가 파일 생성 내용을 보여 주면 승인한다.
2. 만들어진 파일을 확인한다. my-profile.html 파일이 생겼고, 열어 보면 <header>·<main>·<footer> 태그가 쓰여 있다 — 2.3에서 컨텍스트 파일에 넣은 규칙이 지시 없이도 적용된 것이다.
3. 이어서 수정을 시킨다: 취미 소개 부분을 목록(ul)으로 바꿔줘
4. 변경 내용을 확인하고 승인한다.

작은 요청 → 결과 확인 → 다음 요청. 이 짧은 순환이 에이전트 사용의 기본 리듬이다. 한 번에 큰 작업을 통째로 맡기면 어디서 의도와 어긋났는지 찾기 어려우므로, 확인할 수 있는 크기로 쪼개 시킨다.

2.5 – 자주 쓰는 세션 명령어

세션 관리 명령어 세 가지만 알면 기본 사용에 부족함이 없다. /로 시작하는 명령어는 에이전트에게 보내는 대화가 아니라 도구 자체를 조작하는 명령이다.

1. /clear — 현재 세션을 초기화한다. 새 주제로 넘어갈 때 쓴다.
2. /compact — 앞부분 대화를 요약해 컨텍스트 사용량을 줄인다. 긴 세션이 무거워질 때 쓴다.
3. /help — 사용할 수 있는 명령어 목록을 표시한다.