Claude with the Anthropic API #9 — Claude Code & Computer Use

이번에는 Coursera Building with the Claude API 강의의 여섯 번째 Module인 Claude Code & Computer Use를 정리해본다.

앞선 Module에서는 Claude API에 Tool을 연결하고, MCP로 외부 기능을 표준화하며, RAG로 필요한 지식을 검색하는 방법을 살펴봤다. 이번 Module은 그 기능을 실제 개발 환경과 GUI 환경으로 확장한다.

Claude Code는 Terminal에서 Codebase를 읽고, File을 수정하고, Command를 실행하는 Agentic Coding Tool이다. Computer Use는 Claude가 Screenshot을 보고 Mouse와 Keyboard 동작을 요청해 GUI를 조작할 수 있도록 하는 API 기능이다.

Claude Code
→ 개발자의 Terminal과 Codebase에서 작업한다.

Computer Use
→ Screenshot을 해석하고 Mouse·Keyboard Action으로 GUI를 조작한다.

이번 글은 Coursera Module 6의 영상 8개를 강의 순서 그대로 모두 다룬다.

1. Anthropic Apps
2. Claude Code Setup
3. Claude Code in Action
4. Enhancements with MCP Servers
5. Parallelizing Claude Code
6. Automated Debugging
7. Computer Use
8. How Computer Use Works

1. Anthropic Apps

Claude API는 개발자가 직접 Application을 만들 수 있게 해주는 기반이다. Anthropic은 이 API와 Tool Use를 활용한 대표적인 Application으로 Claude Code와 Computer Use를 제공한다.

Claude Code
├─ File 읽기와 검색
├─ Code 작성과 수정
├─ Test·Build·Git Command 실행
└─ 결과 확인 후 다음 작업 수행

Computer Use
├─ 현재 화면 Screenshot 확인
├─ 좌표와 UI 요소 추론
├─ Mouse·Keyboard Action 요청
└─ 새 Screenshot으로 결과 확인

두 기능의 공통점은 한 번의 질문에 Text만 반환하고 끝나지 않는다는 것이다. Claude가 환경을 관찰하고, Tool을 선택하고, 실행 결과를 다시 읽으며 목표를 향해 여러 Turn을 반복한다.

차이는 실행 환경에 있다. Claude Code에는 File System, Shell, Code Search처럼 개발에 특화된 Tool이 주어진다. Computer Use에는 Screenshot, Click, Type, Scroll처럼 사람이 Computer를 다루는 방식과 유사한 Tool이 주어진다.

2. Claude Code Setup

Claude Code는 Terminal에서 실행하는 Agentic Coding Tool이다. 현재 공식 문서에서는 macOS, Linux, Windows 환경을 지원하며 설치 방식은 바뀔 수 있으므로 실제 설치 전 최신 문서를 확인하는 편이 좋다.

강의에서 사용하는 npm 방식은 다음과 같다.

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

cd your-project
claude

처음 실행하면 Anthropic Console, Claude 유료 Plan 또는 조직이 제공하는 Cloud 환경을 통해 인증한다. API Key나 인증 정보는 Source Code와 Git Repository에 직접 넣지 않아야 한다.

Project Directory에서 claude를 실행하는 이유도 중요하다. Claude Code는 현재 Directory를 작업 범위로 삼아 Project 구조, 설정 File, Source Code와 Git 상태를 파악하기 때문이다.

CLAUDE.md로 Project Context 전달하기

Claude Code에서 /init을 실행하면 Codebase를 살펴보고 CLAUDE.md 초안을 생성한다. 이 File에는 매번 반복해서 설명해야 하는 Project 지식을 적어둘 수 있다.

# Project Guidelines

## Commands
- Build: `./gradlew build`
- Test: `./gradlew test`
- Lint: `./gradlew spotlessCheck`

## Architecture
- Controller는 HTTP 변환만 담당한다.
- Business Logic은 Application Service에 둔다.
- Domain Layer는 외부 Framework에 의존하지 않는다.

## Verification
- 변경 후 관련 Unit Test를 먼저 실행한다.
- API 변경 시 Contract Test도 실행한다.

CLAUDE.md에는 문서에서 쉽게 찾을 수 없는 Command, Architecture 원칙, 검증 방법을 짧고 구체적으로 적는 것이 좋다. 오래된 설명이나 서로 충돌하는 규칙이 쌓이면 오히려 Claude의 판단을 흐릴 수 있으므로 Code와 함께 관리해야 한다.

주요 명령은 다음과 같다.

/init
→ Codebase를 분석하고 CLAUDE.md 초안을 만든다.

/clear
→ 현재 대화 Context를 비우고 새 작업을 시작한다.

# 프로젝트는 Java 21을 사용한다
→ 기억해둘 지침을 CLAUDE.md에 빠르게 추가한다.

3. Claude Code in Action

Claude Code의 기본 작업 Loop는 일반적인 Software 개발 과정과 비슷하다.

요청 이해
   ↓
관련 File과 Project 규칙 탐색
   ↓
변경 계획 수립
   ↓
Code 수정
   ↓
Test·Build·Lint 실행
   ↓
실패 원인 분석 및 재수정
   ↓
변경 내용 요약

단순히 “이 기능을 개선해줘”라고 요청하기보다 목표와 완료 조건을 함께 주면 결과가 안정적이다.

주문 취소 API에 멱등성을 추가해줘.

완료 조건:
- 같은 idempotency key로 재요청하면 최초 응답을 반환한다.
- 서로 다른 사용자의 key는 충돌하지 않는다.
- 기존 API Contract는 변경하지 않는다.
- Unit Test와 Integration Test를 추가하고 실행한다.

Claude Code는 관련 File을 찾아 읽고 필요한 부분을 수정할 수 있지만, 생성된 변경을 무조건 신뢰해서는 안 된다. 특히 Database Migration, 인증·권한, 결제, 외부 API 호출처럼 영향 범위가 큰 변경은 Diff와 Test 결과를 사람이 검토해야 한다.

좋은 작업 단위 만들기

한 번에 “서비스 전체를 개선해줘”라고 하면 완료 조건이 모호하고 검증도 어렵다. 독립적으로 확인할 수 있는 작은 작업으로 나누는 편이 좋다.

나쁜 작업 단위
→ 결제 서비스를 더 좋게 만들어줘.

좋은 작업 단위
→ PaymentClient의 Timeout을 설정 가능하게 바꾸고,
  기본값 2초와 Timeout 발생 Test를 추가해줘.

Claude Code가 Command 실행이나 File 수정 전에 Permission을 요청할 수 있다. 편의를 위해 권한을 넓히기보다 작업에 필요한 최소 범위만 허용하고, 파괴적이거나 되돌리기 어려운 작업은 반드시 확인하는 것이 안전하다.

4. Enhancements with MCP Servers

Claude Code의 기본 Tool은 Local Codebase 작업에 강하지만, 실제 개발에는 Issue Tracker, Database, Monitoring, 사내 문서처럼 외부 Context가 필요하다. MCP Server를 연결하면 이런 Data Source와 Tool을 표준 방식으로 Claude Code에 제공할 수 있다.

Claude Code
    ↓ MCP
MCP Server
├─ 사내 문서 검색
├─ Issue 조회
├─ Monitoring Event 확인
└─ Custom 개발 Tool 실행

강의 예시처럼 Local MCP Server는 다음 형태로 등록할 수 있다.

claude mcp add documents -- uv run main.py

등록 후에는 상태를 확인한다.

claude mcp list
claude mcp get documents

MCP Tool은 이름만 보고도 목적을 알 수 있어야 하고, Parameter Schema와 설명에는 언제 사용해야 하는지 분명히 적어야 한다.

from fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("documents")

@mcp.tool()
def search_runbook(
    query: str = Field(description="장애 증상 또는 오류 코드"),
) -> str:
    """운영 Runbook에서 장애 대응 절차를 검색한다."""
    return runbook_index.search(query)

if __name__ == "__main__":
    mcp.run()

MCP Server를 연결했다고 해서 Claude에게 무제한 권한을 주는 것은 아니다. 읽기 Tool과 쓰기 Tool을 구분하고, 배포·삭제·결제처럼 외부 상태를 바꾸는 작업에는 별도 승인 단계를 두는 것이 좋다. Project 단위 설정을 Repository에 공유할 때는 Secret을 설정 File에 포함하지 않아야 한다.

5. Parallelizing Claude Code

서로 의존하지 않는 작업은 여러 Claude Code Instance에서 병렬로 진행할 수 있다. 예를 들어 Backend 구현, Frontend 구현, Test 보강처럼 작업 영역이 분리되어 있다면 순차 실행보다 빠르게 처리할 수 있다.

                    ┌─ Instance A: Backend API 구현
큰 작업 분해 ───────┼─ Instance B: Frontend 화면 구현
                    └─ Instance C: Test Case와 문서 작성
                                      ↓
                              결과 검토 및 통합

다만 같은 Working Tree와 같은 File을 여러 Instance가 동시에 수정하면 충돌하거나 한쪽 변경을 덮어쓸 수 있다. Git Worktree를 사용하면 각 작업을 독립된 Directory와 Branch에서 진행할 수 있다.

git worktree add ../project-api -b feature/order-api
git worktree add ../project-ui -b feature/order-ui
git worktree add ../project-test -b test/order-flow

각 Worktree에서 별도의 Claude Code Session을 실행하고, 작업이 끝나면 Commit이나 Diff 단위로 검토해 통합한다.

병렬화하기 좋은 작업은 다음 조건을 만족한다.

• 수정할 File과 책임 영역이 서로 겹치지 않는다.
• 입력과 기대 결과를 각각 독립적으로 설명할 수 있다.
• 각 작업을 별도로 Build하거나 Test할 수 있다.
• 결과를 합치는 기준이 명확하다.

반대로 Database Schema가 먼저 정해져야 API를 만들 수 있는 경우처럼 선행 작업의 결과가 필요한 일은 억지로 병렬화하지 않는 편이 낫다. 병렬 실행 자체보다 의존성에 맞게 작업 경계를 나누는 것이 핵심이다.

6. Automated Debugging

Claude Code는 Error Message 하나만 보고 답을 추측하는 대신, 재현과 검증을 반복하는 Debugging Loop를 수행할 수 있다.

실패 재현
   ↓
Stack Trace·Log·관련 Code 수집
   ↓
원인 Hypothesis 수립
   ↓
최소 변경 적용
   ↓
실패했던 Test 재실행
   ↓
관련 Regression Test 실행

예를 들어 다음처럼 재현 Command와 성공 조건을 함께 전달한다.

`./gradlew test --tests OrderServiceTest.cancelExpiredOrder`가 실패한다.
먼저 그대로 실행해 실패를 재현하고 원인을 찾아줘.
수정 후에는 해당 Test와 Order Service 전체 Test를 실행해줘.
Test를 삭제하거나 Assertion을 약하게 바꾸면 안 된다.

좋은 자동 Debugging은 “Build가 성공했다”에서 끝나지 않는다. 최초 증상이 사라졌는지, 주변 기능이 깨지지 않았는지, 수정이 원인을 해결했는지 확인해야 한다.

Debugging Prompt에 포함할 정보

• 실패를 재현하는 정확한 Command
• 기대 결과와 실제 결과
• 최근 변경 또는 문제가 시작된 시점
• 관련 Log와 Stack Trace 위치
• 수정 가능한 범위와 건드리면 안 되는 영역
• 완료 후 실행해야 할 Test

Flaky Test처럼 동일한 Command가 항상 실패하지 않는 문제는 한 번의 성공만으로 해결됐다고 판단하기 어렵다. 반복 실행, Seed 고정, 시간·Network 의존성 분리 등 문제 성격에 맞는 검증이 추가로 필요하다.

7. Computer Use

Computer Use는 Claude가 Desktop 환경을 직접 실행하는 제품이 아니라, Application이 제공한 가상 Display와 Computer Tool을 Claude가 사용하도록 만드는 API Pattern이다. Claude는 Screenshot을 보고 다음 Action을 결정하며, 실제 Mouse와 Keyboard Event는 개발자가 만든 실행 환경이 처리한다.

Computer Use가 필요한 대표적인 경우는 다음과 같다.

• API가 없는 Legacy Application 조작
• Web UI의 End-to-End Test
• 여러 화면을 오가는 반복적인 Data 입력
• Screenshot을 바탕으로 한 Visual 검증

하지만 가능한 경우에는 전용 API나 구조화된 Tool이 더 안정적이다. GUI는 Layout 변경, Popup, Network 지연, 해상도 차이에 민감하고 Screenshot 처리 비용도 발생하기 때문이다.

구조화된 API가 있음
→ API 또는 일반 Tool Use를 우선 고려한다.

GUI로만 가능한 작업
→ 격리된 환경에서 Computer Use를 고려한다.

Computer Use에는 현실적인 위험도 있다. Claude가 잘못된 위치를 Click하거나, Web Page 안의 악의적인 지시를 따라가거나, 의도하지 않은 외부 변경을 만들 수 있다. 따라서 다음과 같은 안전장치가 필요하다.

• VM이나 Container 같은 격리된 실행 환경 사용
• 접근 가능한 Domain과 Application 제한
• 계정의 권한과 보유 Data 최소화
• 구매, 전송, 삭제 등 중요한 작업 전 사용자 확인
• 입력·Screenshot·Action과 결과에 대한 Logging
• Web Page와 문서의 문구를 신뢰할 수 없는 Data로 취급

8. How Computer Use Works

Computer Use도 Claude API의 일반적인 Tool Use Loop를 따른다. 차이는 Tool의 입력이 좌표, Key, Scroll 같은 Computer Action이라는 점이다.

Application이 초기 Screenshot과 요청 전달
                    ↓
Claude가 화면을 해석하고 Tool Use 요청
예: mouse_move, left_click, type, key, screenshot
                    ↓
Application이 격리된 환경에서 Action 실행
                    ↓
새 Screenshot을 Tool Result로 반환
                    ↓
Claude가 완료할 때까지 반복

개념적인 Python 구현은 다음과 같다. 실제 API Version과 Tool Type은 변경될 수 있으므로 최신 Anthropic 문서를 기준으로 맞춰야 한다.

messages = [{"role": "user", "content": task}]

while True:
    response = client.beta.messages.create(
        model=MODEL,
        max_tokens=4096,
        tools=[computer_tool_definition],
        messages=messages,
        betas=[COMPUTER_USE_BETA],
    )

    messages.append({"role": "assistant", "content": response.content})

    tool_uses = [
        block for block in response.content
        if block.type == "tool_use"
    ]

    if not tool_uses:
        break

    tool_results = []
    for tool_use in tool_uses:
        result = sandbox.execute(tool_use.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": result,
        })

    messages.append({"role": "user", "content": tool_results})

핵심은 Claude가 직접 Operating System을 조작하는 것이 아니라는 점이다. 개발자의 Application이 Tool 요청을 검증하고 실행한 뒤 결과를 돌려준다. 따라서 허용 Action, 좌표 범위, 대상 Domain, Session Timeout과 승인 정책을 실행기에서 강제해야 한다.

Screenshot 기반 동작의 한계

Claude는 화면의 Pixel을 보고 UI를 추론하므로 다음 상황에서 오류 가능성이 커진다.

• 화면이 작거나 글자가 흐린 경우
• Animation이나 Loading으로 화면이 계속 변하는 경우
• Click 대상이 너무 작거나 서로 붙어 있는 경우
• Popup이 예고 없이 나타나는 경우
• Scroll 뒤 요소의 위치가 달라지는 경우

Action마다 새 Screenshot으로 상태를 확인하고, 실패 시 무한 반복하지 않도록 최대 Step과 Timeout을 두어야 한다. 중요한 상태 변경은 Screenshot만으로 추측하지 말고 성공 Message, URL, Download 결과처럼 별도의 증거로 검증하는 편이 안전하다.

9. Claude Code와 Computer Use를 선택하는 기준

두 기능 모두 Agentic Loop를 사용하지만 대체 관계는 아니다.

Source Code 수정·Test·Build·Git 작업
→ Claude Code

Browser나 Desktop GUI 조작
→ Computer Use

외부 서비스가 안정적인 API를 제공함
→ API Tool 또는 MCP Server

개발부터 UI 검증까지 필요함
→ Claude Code + Browser/Computer Tool 조합

가장 안정적인 Interface부터 선택하면 된다. 일반적으로 구조화된 API가 GUI보다 예측 가능하고, Code 전용 Tool이 화면에서 Text를 복사하는 것보다 정확하다. Computer Use는 다른 Interface가 없거나 실제 사용자 화면을 검증해야 할 때 가치가 크다.

10. Production 적용 시 확인할 것

Claude Code
├─ Project 규칙과 검증 Command 문서화
├─ 최소 권한과 중요 작업 승인
├─ Diff·Test 결과 Review
├─ 병렬 작업의 Worktree 격리
└─ Secret과 민감 File 보호

Computer Use
├─ VM·Container 격리
├─ Domain·Action Allowlist
├─ 최대 Step·Timeout·비용 제한
├─ 중요 작업 Human-in-the-loop
├─ Prompt Injection 방어
└─ Screenshot·Action Audit Log

두 기능을 Production Workflow에 넣을 때는 “Model이 얼마나 똑똑한가”보다 어떤 환경과 권한을 주었고, 실패를 어떻게 감지하며, 잘못된 Action을 어디서 막는가가 더 중요하다.

11. 전체 정리

Anthropic Apps
→ Claude Code와 Computer Use는 Tool Use를 실제 환경으로 확장한다.

Claude Code Setup
→ Project Directory에서 실행하고 CLAUDE.md로 반복 Context를 관리한다.

Claude Code in Action
→ 탐색, 수정, Test, 검증을 하나의 개발 Loop로 수행한다.

Enhancements with MCP Servers
→ 외부 Data와 Custom Tool을 표준 Interface로 연결한다.

Parallelizing Claude Code
→ 독립 작업을 분리하고 Worktree로 File 충돌을 피한다.

Automated Debugging
→ 재현, 원인 분석, 수정, Regression Test를 반복한다.

Computer Use
→ API가 없는 GUI 작업과 Visual 검증을 자동화한다.

How Computer Use Works
→ Screenshot과 Computer Action을 Tool Use Loop로 주고받는다.

Claude Code와 Computer Use의 핵심은 Claude가 한 번에 정답 Code나 정답 Click을 만들어내는 데 있지 않다. 현재 환경을 관찰하고, 필요한 Action을 선택하고, 실행 결과를 확인하며 다음 행동을 조정하는 Loop에 있다.

이 Loop에 명확한 완료 조건, 충분한 검증 수단, 최소 권한과 중단 조건을 제공해야 실제 개발과 자동화에서도 신뢰할 수 있다.

12. Coursera Module 6 누락 확인

이번 글에 반영한 강의 구성은 다음과 같다.

• 영상 8개: Anthropic Apps, Claude Code Setup, Claude Code in Action, Enhancements with MCP Servers, Parallelizing Claude Code, Automated Debugging, Computer Use, How Computer Use Works
• 읽기 2개: Introduction to the course, Next steps
• 퀴즈 2개: Quiz on Claude Code, Quiz on Computer Use

다음 Module 7에서는 Agentic Workflows로 넘어가 Parallelization, Chaining, Routing Workflow와 Agent의 차이를 정리할 예정이다.

참고 자료

• Coursera — Building with the Claude API
• Anthropic — Claude Code overview
• Anthropic — Set up Claude Code
• Anthropic — Connect Claude Code to tools via MCP
• Anthropic — Computer use tool