Summary
Anthropic์ Claude Code SDK๋ ๊ฐ๋ฐ์๊ฐ Claude์ ์ฝ๋ฉ ๋ฅ๋ ฅ์ ์ ํ๋ฆฌ์ผ์ด์ ์ ํตํฉํ ์ ์๋๋ก ์ง์ํฉ๋๋ค. ์ด SDK๋ ๋ช ๋ น์ค, TypeScript, Python์ ํตํด ์ฌ์ฉํ ์ ์์ผ๋ฉฐ, Claude Code๋ฅผ ์๋ธ ํ๋ก์ธ์ค๋ก ์คํํ์ฌ AI ๊ธฐ๋ฐ ์ฝ๋ฉ ๋์ฐ๋ฏธ๋ฅผ ๊ตฌ์ถํ ์ ์๊ฒ ํฉ๋๋ค. API ํค ์ธ์ฆ, ๊ธฐ๋ณธ ์ฌ์ฉ๋ฒ, ๋ค์ค ํด ๋ํ, ์ฌ์ฉ์ ์ ์ ์์คํ ํ๋กฌํํธ, MCP ๊ตฌ์ฑ, CLI ์ต์ , ์ถ๋ ฅ ํ์ ๋ฑ ๋ค์ํ ๊ธฐ๋ฅ์ ์ ๊ณตํ๋ฉฐ, ์ค์ ์ ํ๋ฆฌ์ผ์ด์ ํตํฉ ๋ฐ ๊ด๋ จ ๋ฆฌ์์ค์ ๋ํ ์ ๋ณด๋ ํฌํจํฉ๋๋ค.
Claude Code SDK๋ฅผ ํตํด Claude Code๋ฅผ ์ ํ๋ฆฌ์ผ์ด์ ์ ํ๋ก๊ทธ๋จ ๋ฐฉ์์ผ๋ก ํตํฉํ๋ ๋ฐฉ๋ฒ์ ๋ํด ์ค๋ช ํฉ๋๋ค.
Claude Code SDK๋ ๊ฐ๋ฐ์๊ฐ Claude Code๋ฅผ ์ ํ๋ฆฌ์ผ์ด์ ์ ํ๋ก๊ทธ๋จ ๋ฐฉ์์ผ๋ก ํตํฉํ ์ ์๋๋ก ํ์ฉํฉ๋๋ค. ์ด SDK๋ Claude Code๋ฅผ ์๋ธ ํ๋ก์ธ์ค๋ก ์คํํ์ฌ Claude์ ๊ธฐ๋ฅ์ ํ์ฉํ๋ AI ๊ธฐ๋ฐ ์ฝ๋ฉ ๋์ฐ๋ฏธ ๋ฐ ๋๊ตฌ๋ฅผ ๊ตฌ์ถํ๋ ๋ฐฉ๋ฒ์ ์ ๊ณตํฉ๋๋ค.
์ด SDK๋ ๋ช ๋ น์ค, TypeScript, Python์์ ์ฌ์ฉ ๊ฐ๋ฅํฉ๋๋ค.
์ธ์ฆ
Claude Code SDK๋ฅผ ์ฌ์ฉํ๋ ค๋ฉด ์ ์ฉ API ํค๋ฅผ ์์ฑํ๋ ๊ฒ์ด ์ข์ต๋๋ค.
- Anthropic Console์์ Anthropic API ํค๋ฅผ ์์ฑํ์ญ์์ค.
- ๊ทธ๋ฐ ๋ค์,
ANTHROPIC_API_KEY
ํ๊ฒฝ ๋ณ์๋ฅผ ์ค์ ํ์ญ์์ค. ์ด ํค๋ ์์ ํ๊ฒ ์ ์ฅํ๋ ๊ฒ์ ๊ถ์ฅํฉ๋๋ค(์: GitHub ์ํฌ๋ฆฟ ์ฌ์ฉ).
SDK ๊ธฐ๋ณธ ์ฌ์ฉ๋ฒ
Claude Code SDK๋ฅผ ํตํด ์ ํ๋ฆฌ์ผ์ด์ ์์ Claude Code๋ฅผ ๋น๋ํํ ๋ชจ๋๋ก ์ฌ์ฉํ ์ ์์ต๋๋ค.
๋ช ๋ น์ค
๋ค์์ ๋ช ๋ น์ค SDK์ ๋ช ๊ฐ์ง ๊ธฐ๋ณธ ์์์ ๋๋ค.
# ๋จ์ผ ํ๋กฌํํธ๋ฅผ ์คํํ๊ณ ์ข
๋ฃํฉ๋๋ค (์ธ์ ๋ชจ๋).
$ claude -p "ํผ๋ณด๋์น ์ซ์๋ฅผ ๊ณ์ฐํ๋ ํจ์๋ฅผ ์์ฑํ์ญ์์ค."
# ํ์ดํ๋ฅผ ์ฌ์ฉํ์ฌ ํ์ค ์
๋ ฅ์ ์ ๊ณตํฉ๋๋ค.
$ echo "์ด ์ฝ๋๋ฅผ ์ค๋ช
ํ์ญ์์ค." | claude -p
# ๋ฉํ๋ฐ์ดํฐ์ ํจ๊ป JSON ํ์์ผ๋ก ์ถ๋ ฅํฉ๋๋ค.
$ claude -p "Hello World ํจ์๋ฅผ ์์ฑํ์ญ์์ค." --output-format json
# JSON ์ถ๋ ฅ์ด ๋์ฐฉํ๋ ๋๋ก ์คํธ๋ฆฌ๋ฐํฉ๋๋ค.
$ claude -p "React ์ปดํฌ๋ํธ๋ฅผ ๋น๋ํ์ญ์์ค." --output-format stream-json
TypeScript
TypeScript SDK๋ NPM์ ์ฃผ์ @anthropic-ai/claude-code
ํจํค์ง์ ํฌํจ๋์ด ์์ต๋๋ค.
import { query, type SDKMessage } from "@anthropic-ai/claude-code";
const messages: SDKMessage[] = [];
for await (const message of query({
prompt: "foo.py์ ๋ํ ํ์ด์ฟ ๋ฅผ ์์ฑํ์ญ์์ค.",
abortController: new AbortController(),
options: {
maxTurns: 3,
},
})) {
messages.push(message);
}
console.log(messages);
TypeScript SDK๋ ๋ช ๋ น์ค SDK์์ ์ง์ํ๋ ๋ชจ๋ ์ธ์๋ฅผ ํ์ฉํ๋ฉฐ, ๋ค์๋ ํฌํจํฉ๋๋ค.
abortController
: Abort ์ปจํธ๋กค๋ฌ์ ๋๋ค. ๊ธฐ๋ณธ๊ฐ์new AbortController()
์ ๋๋ค.cwd
: ํ์ฌ ์์ ๋๋ ํฐ๋ฆฌ์ ๋๋ค. ๊ธฐ๋ณธ๊ฐ์process.cwd()
์ ๋๋ค.executable
: ์ฌ์ฉํ JavaScript ๋ฐํ์์ ๋๋ค. Node.js์์ ์คํ ์node
, Bun์์ ์คํ ์bun
์ ๋๋ค.executableArgs
: ์คํ ํ์ผ์ ์ ๋ฌํ ์ธ์์ ๋๋ค. ๊ธฐ๋ณธ๊ฐ์[]
์ ๋๋ค.pathToClaudeCodeExecutable
: Claude Code ์คํ ํ์ผ์ ๊ฒฝ๋ก์ ๋๋ค. ๊ธฐ๋ณธ๊ฐ์@anthropic-ai/claude-code
์ ํจ๊ป ์ ๊ณต๋๋ ์คํ ํ์ผ์ ๋๋ค.
Python
Python SDK๋ PyPI์์ claude-code-sdk
๋ก ์ฌ์ฉ ๊ฐ๋ฅํฉ๋๋ค.
pip install claude-code-sdk
์ฌ์ ์๊ตฌ ์ฌํญ์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
- Python 3.10 ์ด์
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
๊ธฐ๋ณธ ์ฌ์ฉ๋ฒ์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message
async def main():
messages: list[Message] = []
async for message in query(
prompt="foo.py์ ๋ํ ํ์ด์ฟ ๋ฅผ ์์ฑํ์ญ์์ค.",
options=ClaudeCodeOptions(max_turns=3)
):
messages.append(message)
print(messages)
anyio.run(main)
Python SDK๋ ClaudeCodeOptions
ํด๋์ค๋ฅผ ํตํด ๋ช
๋ น์ค SDK์์ ์ง์ํ๋ ๋ชจ๋ ์ธ์๋ฅผ ํ์ฉํฉ๋๋ค.
from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path
options = ClaudeCodeOptions(
max_turns=3,
system_prompt="๋น์ ์ ์ ์ฉํ ๋น์์
๋๋ค.",
cwd=Path("/path/to/project"), # ๋ฌธ์์ด ๋๋ Path์ผ ์ ์์ต๋๋ค.
allowed_tools=["Read", "Write", "Bash"],
permission_mode="acceptEdits"
)
async for message in query(prompt="์๋
ํ์ธ์", options=options):
print(message)
๊ณ ๊ธ ์ฌ์ฉ๋ฒ
์๋ ๋ฌธ์๋ ๋ช ๋ น์ค SDK๋ฅผ ์์๋ก ์ฌ์ฉํ์ง๋ง, TypeScript ๋ฐ Python SDK์์๋ ์ฌ์ฉํ ์ ์์ต๋๋ค.
๋ค์ค ํด ๋ํ
๋ค์ค ํด ๋ํ์ ๊ฒฝ์ฐ, ๋ํ๋ฅผ ์ฌ๊ฐํ๊ฑฐ๋ ๊ฐ์ฅ ์ต๊ทผ ์ธ์ ์์ ๊ณ์ํ ์ ์์ต๋๋ค.
# ๊ฐ์ฅ ์ต๊ทผ ๋ํ๋ฅผ ๊ณ์ํฉ๋๋ค.
$ claude --continue
# ๊ณ์ํ๊ณ ์๋ก์ด ํ๋กฌํํธ๋ฅผ ์ ๊ณตํฉ๋๋ค.
$ claude --continue "์ด์ ๋ ๋์ ์ฑ๋ฅ์ ์ํด ์ด๊ฒ์ ๋ฆฌํฉํฐ๋งํ์ญ์์ค."
# ์ธ์
ID๋ก ํน์ ๋ํ๋ฅผ ์ฌ๊ฐํฉ๋๋ค.
$ claude --resume 550e8400-e29b-41d4-a716-446655440000
# ์ธ์ ๋ชจ๋(๋น๋ํํ)๋ก ์ฌ๊ฐํฉ๋๋ค.
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "ํ
์คํธ๋ฅผ ์
๋ฐ์ดํธํ์ญ์์ค."
# ์ธ์ ๋ชจ๋(๋น๋ํํ)๋ก ๊ณ์ํฉ๋๋ค.
$ claude -p --continue "์ค๋ฅ ์ฒ๋ฆฌ๋ฅผ ์ถ๊ฐํ์ญ์์ค."
์ฌ์ฉ์ ์ ์ ์์คํ ํ๋กฌํํธ
Claude์ ๋์์ ์๋ดํ๊ธฐ ์ํด ์ฌ์ฉ์ ์ ์ ์์คํ ํ๋กฌํํธ๋ฅผ ์ ๊ณตํ ์ ์์ต๋๋ค.
# ์์คํ
ํ๋กฌํํธ๋ฅผ ์ฌ์ ์ํฉ๋๋ค (--print์์๋ง ์๋ํฉ๋๋ค).
$ claude -p "REST API๋ฅผ ๋น๋ํ์ญ์์ค." --system-prompt "๋น์ ์ ์ ์ ๋ฐฑ์๋ ์์ง๋์ด์
๋๋ค. ๋ณด์, ์ฑ๋ฅ ๋ฐ ์ ์ง๋ณด์์ฑ์ ์ค์ ์ ๋์ญ์์ค."
# ํน์ ์๊ตฌ์ฌํญ์ด ์๋ ์์คํ
ํ๋กฌํํธ์
๋๋ค.
$ claude -p "๋ฐ์ดํฐ๋ฒ ์ด์ค ์คํค๋ง๋ฅผ ์์ฑํ์ญ์์ค." --system-prompt "๋น์ ์ ๋ฐ์ดํฐ๋ฒ ์ด์ค ์ํคํ
ํธ์
๋๋ค. PostgreSQL ๋ชจ๋ฒ ์ฌ๋ก๋ฅผ ์ฌ์ฉํ๊ณ ์ ์ ํ ์ธ๋ฑ์ฑ์ ํฌํจํ์ญ์์ค."
๊ธฐ๋ณธ ์์คํ ํ๋กฌํํธ์ ์ง์นจ์ ์ถ๊ฐํ ์๋ ์์ต๋๋ค.
# ์์คํ
ํ๋กฌํํธ๋ฅผ ์ถ๊ฐํฉ๋๋ค (--print์์๋ง ์๋ํฉ๋๋ค).
$ claude -p "REST API๋ฅผ ๋น๋ํ์ญ์์ค." --append-system-prompt "์ฝ๋๋ฅผ ์์ฑํ ํ์๋ ๋ฐ๋์ ์ง์ ์ฝ๋ ๊ฒํ ๋ฅผ ํ์ญ์์ค."
MCP ๊ตฌ์ฑ
๋ชจ๋ธ ์ปจํ
์คํธ ํ๋กํ ์ฝ(MCP)์ ์ฌ์ฉํ๋ฉด ์ธ๋ถ ์๋ฒ์ ์ถ๊ฐ ๋๊ตฌ ๋ฐ ๋ฆฌ์์ค๋ก Claude Code๋ฅผ ํ์ฅํ ์ ์์ต๋๋ค. --mcp-config
ํ๋๊ทธ๋ฅผ ์ฌ์ฉํ์ฌ ๋ฐ์ดํฐ๋ฒ ์ด์ค ์ก์ธ์ค, API ํตํฉ ๋๋ ์ฌ์ฉ์ ์ ์ ๋๊ตฌ์ ๊ฐ์ ํน์ ๊ธฐ๋ฅ์ ์ ๊ณตํ๋ MCP ์๋ฒ๋ฅผ ๋ก๋ํ ์ ์์ต๋๋ค.
MCP ์๋ฒ๊ฐ ํฌํจ๋ JSON ๊ตฌ์ฑ ํ์ผ์ ์์ฑํ์ญ์์ค.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/files"
]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-github-token"
}
}
}
}
๊ทธ๋ฐ ๋ค์ Claude Code์์ ์ฌ์ฉํ์ญ์์ค.
# ๊ตฌ์ฑ์์ MCP ์๋ฒ๋ฅผ ๋ก๋ํฉ๋๋ค.
$ claude -p "ํ๋ก์ ํธ์ ๋ชจ๋ ํ์ผ์ ๋์ดํ์ญ์์ค." --mcp-config mcp-servers.json
# ์ค์: MCP ๋๊ตฌ๋ --allowedTools๋ฅผ ์ฌ์ฉํ์ฌ ๋ช
์์ ์ผ๋ก ํ์ฉ๋์ด์ผ ํฉ๋๋ค.
# MCP ๋๊ตฌ๋ mcp__$serverName__$toolName ํ์์ ๋ฐ๋ฆ
๋๋ค.
$ claude -p "TODO ์ฃผ์์ ๊ฒ์ํ์ญ์์ค." \
--mcp-config mcp-servers.json \
--allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"
# ๋น๋ํํ ๋ชจ๋์์ ๊ถํ ํ๋กฌํํธ๋ฅผ ์ฒ๋ฆฌํ๊ธฐ ์ํด MCP ๋๊ตฌ๋ฅผ ์ฌ์ฉํฉ๋๋ค.
$ claude -p "์ ํ๋ฆฌ์ผ์ด์
์ ๋ฐฐํฌํ์ญ์์ค." \
--mcp-config mcp-servers.json \
--allowedTools "mcp__permissions__approve" \
--permission-prompt-tool mcp__permissions__approve
Info
MCP ๋๊ตฌ๋ฅผ ์ฌ์ฉํ ๋๋
--allowedTools
ํ๋๊ทธ๋ฅผ ์ฌ์ฉํ์ฌ ๋ช ์์ ์ผ๋ก ํ์ฉํด์ผ ํฉ๋๋ค. MCP ๋๊ตฌ ์ด๋ฆ์mcp__<serverName>__<toolName>
ํจํด์ ๋ฐ๋ฅด๋ฉฐ, ์ฌ๊ธฐ์serverName
์ MCP ๊ตฌ์ฑ ํ์ผ์ ํค์ด๊ณtoolName
์ ํด๋น ์๋ฒ์์ ์ ๊ณตํ๋ ํน์ ๋๊ตฌ์ ๋๋ค.์ด ๋ณด์ ์กฐ์น๋ MCP ๋๊ตฌ๊ฐ ๋ช ์์ ์ผ๋ก ํ์ฉ๋ ๋๋ง ์ฌ์ฉ๋๋๋ก ๋ณด์ฅํฉ๋๋ค.
์๋ฒ ์ด๋ฆ๋ง ์ง์ ํ๋ ๊ฒฝ์ฐ(์:
mcp__<serverName>
), ํด๋น ์๋ฒ์ ๋ชจ๋ ๋๊ตฌ๊ฐ ํ์ฉ๋ฉ๋๋ค.์ ์ญ ํจํด(์:
mcp__go*
)์ ์ง์๋์ง ์์ต๋๋ค.
์ฌ์ฉ์ ์ ์ ๊ถํ ํ๋กฌํํธ ๋๊ตฌ
์ ํ์ ์ผ๋ก --permission-prompt-tool
์ ์ฌ์ฉํ์ฌ ์ฌ์ฉ์๊ฐ ํน์ ๋๊ตฌ๋ฅผ ํธ์ถํ ๊ถํ์ ๋ชจ๋ธ์ ๋ถ์ฌํ๋์ง ํ์ธํ ๋ ์ฌ์ฉํ MCP ๋๊ตฌ๋ฅผ ์ ๋ฌํ ์ ์์ต๋๋ค. ๋ชจ๋ธ์ด ๋๊ตฌ๋ฅผ ํธ์ถํ๋ฉด ๋ค์์ด ๋ฐ์ํฉ๋๋ค.
- ๋จผ์ ๊ถํ ์ค์ ์ ํ์ธํฉ๋๋ค. ๋ชจ๋
settings.json
ํ์ผ๋ฟ๋ง ์๋๋ผ SDK์ ์ ๋ฌ๋--allowedTools
๋ฐ--disallowedTools
๋ฅผ ํ์ธํฉ๋๋ค. ์ด ์ค ํ๋๊ฐ ๋๊ตฌ ํธ์ถ์ ํ์ฉํ๊ฑฐ๋ ๊ฑฐ๋ถํ๋ฉด ๋๊ตฌ ํธ์ถ์ ์งํํฉ๋๋ค. - ๊ทธ๋ ์ง ์์ผ๋ฉด
--permission-prompt-tool
์ ์ ๊ณตํ MCP ๋๊ตฌ๋ฅผ ํธ์ถํฉ๋๋ค.
--permission-prompt-tool
MCP ๋๊ตฌ๋ ๋๊ตฌ ์ด๋ฆ๊ณผ ์
๋ ฅ์ ์ ๋ฌ๋ฐ์ผ๋ฉฐ, ๊ฒฐ๊ณผ์ ํจ๊ป JSON ๋ฌธ์์ดํ๋ ํ์ด๋ก๋๋ฅผ ๋ฐํํด์ผ ํฉ๋๋ค. ํ์ด๋ก๋๋ ๋ค์ ์ค ํ๋์ฌ์ผ ํฉ๋๋ค.
// ๋๊ตฌ ํธ์ถ์ด ํ์ฉ๋ฉ๋๋ค.
{
"behavior": "allow",
"updatedInput": {...}, // ์
๋ฐ์ดํธ๋ ์
๋ ฅ ๋๋ ์๋ณธ ์
๋ ฅ ๋ฐํ
}
// ๋๊ตฌ ํธ์ถ์ด ๊ฑฐ๋ถ๋ฉ๋๋ค.
{
"behavior": "deny",
"message": "..." // ๊ถํ์ด ๊ฑฐ๋ถ๋ ์ด์ ๋ฅผ ์ค๋ช
ํ๋ ์ฌ๋์ด ์ฝ์ ์ ์๋ ๋ฌธ์์ด
}
์๋ฅผ ๋ค์ด, TypeScript MCP ๊ถํ ํ๋กฌํํธ ๋๊ตฌ ๊ตฌํ์ ๋ค์๊ณผ ๊ฐ์ ์ ์์ต๋๋ค.
const server = new McpServer({
name: "Test permission prompt MCP Server",
version: "0.0.1",
});
server.tool(
"approval_prompt",
'๊ถํ ํ์ธ์ ์๋ฎฌ๋ ์ด์
ํฉ๋๋ค - ์
๋ ฅ์ "allow"๊ฐ ํฌํจ๋์ด ์์ผ๋ฉด ์น์ธํ๊ณ , ๊ทธ๋ ์ง ์์ผ๋ฉด ๊ฑฐ๋ถํฉ๋๋ค.',
{
tool_name: z.string().describe("๊ถํ์ ์์ฒญํ๋ ๋๊ตฌ"),
input: z.object({}).passthrough().describe("๋๊ตฌ์ ๋ํ ์
๋ ฅ"),
},
async ({ tool_name, input }) => {
return {
content: [
{
type: "text",
text: JSON.stringify(
JSON.stringify(input).includes("allow")
? {
behavior: "allow",
updatedInput: input,
}
: {
behavior: "deny",
message: "ํ
์คํธ ์น์ธ ํ๋กฌํํธ ๋๊ตฌ์ ์ํด ๊ถํ์ด ๊ฑฐ๋ถ๋์์ต๋๋ค.",
}
),
},
],
};
}
);
์ด ๋๊ตฌ๋ฅผ ์ฌ์ฉํ๋ ค๋ฉด MCP ์๋ฒ๋ฅผ ์ถ๊ฐํ ๋ค์(์: --mcp-config
์ฌ์ฉ) ๋ค์๊ณผ ๊ฐ์ด SDK๋ฅผ ํธ์ถํ์ญ์์ค.
claude -p "..." \
--permission-prompt-tool mcp__test-server__approval_prompt \
--mcp-config my-config.json
์ฌ์ฉ๋ฒ ์ฐธ๊ณ ์ฌํญ์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
updatedInput
์ ์ฌ์ฉํ์ฌ ๊ถํ ํ๋กฌํํธ๊ฐ ์ ๋ ฅ์ ๋ณ๊ฒฝํ์์ ๋ชจ๋ธ์ ์๋ฆฌ์ญ์์ค. ๊ทธ๋ ์ง ์์ผ๋ฉด ์์ ์์์ฒ๋ผupdatedInput
์ ์๋ณธ ์ ๋ ฅ์ผ๋ก ์ค์ ํ์ญ์์ค. ์๋ฅผ ๋ค์ด, ๋๊ตฌ๊ฐ ์ฌ์ฉ์์๊ฒ ํ์ผ ํธ์ง ์ฐจ์ด๋ฅผ ๋ณด์ฌ์ฃผ๊ณ ์๋์ผ๋ก ์ฐจ์ด๋ฅผ ํธ์งํ๋๋ก ํ์ฉํ๋ ๊ฒฝ์ฐ, ๊ถํ ํ๋กฌํํธ ๋๊ตฌ๋ ํด๋น ์ ๋ฐ์ดํธ๋ ํธ์ง์ ๋ฐํํด์ผ ํฉ๋๋ค.- ํ์ด๋ก๋๋ JSON์ผ๋ก ๋ฌธ์์ดํ๋์ด์ผ ํฉ๋๋ค.
์ฌ์ฉ ๊ฐ๋ฅํ CLI ์ต์
SDK๋ Claude Code์์ ์ฌ์ฉํ ์ ์๋ ๋ชจ๋ CLI ์ต์ ์ ํ์ฉํฉ๋๋ค. ๋ค์์ SDK ์ฌ์ฉ์ ์ํ ์ฃผ์ ์ต์ ์ ๋๋ค.
--print
,-p
: ๋น๋ํํ ๋ชจ๋๋ก ์คํํฉ๋๋ค. ์์:claude -p "query"
--output-format
: ์ถ๋ ฅ ํ์์ ์ง์ ํฉ๋๋ค (text
,json
,stream-json
). ์์:claude -p --output-format json
--resume
,-r
: ์ธ์ ID๋ก ๋ํ๋ฅผ ์ฌ๊ฐํฉ๋๋ค. ์์:claude --resume abc123
--continue
,-c
: ๊ฐ์ฅ ์ต๊ทผ ๋ํ๋ฅผ ๊ณ์ํฉ๋๋ค. ์์:claude --continue
--verbose
: ์์ธ ๋ก๊น ์ ํ์ฑํํฉ๋๋ค. ์์:claude --verbose
--max-turns
: ๋น๋ํํ ๋ชจ๋์์ ์์ด์ ํธ ํด์ ์ ํํฉ๋๋ค. ์์:claude --max-turns 3
--system-prompt
: ์์คํ ํ๋กฌํํธ๋ฅผ ์ฌ์ ์ํฉ๋๋ค (--print
์์๋ง ์ฌ์ฉ ๊ฐ๋ฅ). ์์:claude --system-prompt "์ฌ์ฉ์ ์ ์ ์ง์นจ"
--append-system-prompt
: ์์คํ ํ๋กฌํํธ์ ์ถ๊ฐํฉ๋๋ค (--print
์์๋ง ์ฌ์ฉ ๊ฐ๋ฅ). ์์:claude --append-system-prompt "์ฌ์ฉ์ ์ ์ ์ง์นจ"
--allowedTools
: ํ์ฉ๋ ๋๊ตฌ์ ๊ณต๋ฐฑ์ผ๋ก ๊ตฌ๋ถ๋ ๋ชฉ๋ก ๋๋ ์ผํ๋ก ๊ตฌ๋ถ๋ ๋ฌธ์์ด์ ๋๋ค. ์์:claude --allowedTools mcp__slack mcp__filesystem
,claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools
: ๊ฑฐ๋ถ๋ ๋๊ตฌ์ ๊ณต๋ฐฑ์ผ๋ก ๊ตฌ๋ถ๋ ๋ชฉ๋ก ๋๋ ์ผํ๋ก ๊ตฌ๋ถ๋ ๋ฌธ์์ด์ ๋๋ค. ์์:claude --disallowedTools mcp__splunk mcp__github
,claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-config
: JSON ํ์ผ์์ MCP ์๋ฒ๋ฅผ ๋ก๋ํฉ๋๋ค. ์์:claude --mcp-config servers.json
--permission-prompt-tool
: ๊ถํ ํ๋กฌํํธ๋ฅผ ์ฒ๋ฆฌํ๊ธฐ ์ํ MCP ๋๊ตฌ์ ๋๋ค (--print
์์๋ง ์ฌ์ฉ ๊ฐ๋ฅ). ์์:claude --permission-prompt-tool mcp__auth__prompt
CLI ์ต์ ๋ฐ ๊ธฐ๋ฅ์ ์ ์ฒด ๋ชฉ๋ก์ CLI ์ฌ์ฉ ๋ฌธ์๋ฅผ ์ฐธ์กฐํ์ญ์์ค.
์ถ๋ ฅ ํ์
SDK๋ ์ฌ๋ฌ ์ถ๋ ฅ ํ์์ ์ง์ํฉ๋๋ค.
ํ ์คํธ ์ถ๋ ฅ (๊ธฐ๋ณธ๊ฐ)
์๋ต ํ ์คํธ๋ง ๋ฐํํฉ๋๋ค.
$ claude -p "src/components/Header.tsx ํ์ผ์ ์ค๋ช
ํ์ญ์์ค."
# ์ถ๋ ฅ: ์ด๊ฒ์ React ์ปดํฌ๋ํธ์ด๋ฉฐ...
JSON ์ถ๋ ฅ
๋ฉํ๋ฐ์ดํฐ๋ฅผ ํฌํจํ ๊ตฌ์กฐํ๋ ๋ฐ์ดํฐ๋ฅผ ๋ฐํํฉ๋๋ค.
$ claude -p "๋ฐ์ดํฐ ๊ณ์ธต์ ์ด๋ป๊ฒ ์๋ํฉ๋๊น?" --output-format json
์๋ต ํ์์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
{
"type": "result",
"subtype": "success",
"total_cost_usd": 0.003,
"is_error": false,
"duration_ms": 1234,
"duration_api_ms": 800,
"num_turns": 6,
"result": "์ฌ๊ธฐ์ ์๋ต ํ
์คํธ...",
"session_id": "abc123"
}
์คํธ๋ฆฌ๋ฐ JSON ์ถ๋ ฅ
๊ฐ ๋ฉ์์ง๋ฅผ ์์ ํ๋ ์ฆ์ ์คํธ๋ฆฌ๋ฐํฉ๋๋ค.
CLI ๋ช ๋ น ์์
$ claude -p "Build an application" --output-format stream-json
๊ฐ ๋ํ๋ ์ด๊ธฐ init
์์คํ
๋ฉ์์ง๋ก ์์ํ๋ฉฐ, ์ด์ด์ ์ฌ์ฉ์ ๋ฐ ์ด์์คํดํธ ๋ฉ์์ง ๋ชฉ๋ก์ด ์ค๊ณ , ๋ง์ง๋ง์ผ๋ก ํต๊ณ๊ฐ ํฌํจ๋ ์ต์ข
result
์์คํ
๋ฉ์์ง๋ก ๋ง๋ฌด๋ฆฌ๋ฉ๋๋ค. ๊ฐ ๋ฉ์์ง๋ ๋ณ๋์ JSON ๊ฐ์ฒด๋ก ๋ฐฉ์ถ๋ฉ๋๋ค.
๋ฉ์์ง ์คํค๋ง
JSON API์์ ๋ฐํ๋๋ ๋ฉ์์ง๋ ๋ค์ ์คํค๋ง์ ๋ฐ๋ผ ์๊ฒฉํ๊ฒ ์ ํํ๋ฉ๋๋ค.
SDKMessage ํ์ ์ ์
type SDKMessage =
// An assistant message
| {
type: "assistant";
message: Message; // from Anthropic SDK
session_id: string;
}
// A user message
| {
type: "user";
message: MessageParam; // from Anthropic SDK
session_id: string;
}
// Emitted as the last message
| {
type: "result";
subtype: "success";
duration_ms: float;
duration_api_ms: float;
is_error: boolean;
num_turns: int;
result: string;
session_id: string;
total_cost_usd: float;
}
// Emitted as the last message, when we've reached the maximum number of turns
| {
type: "result";
subtype: "error_max_turns" | "error_during_execution";
duration_ms: float;
duration_api_ms: float;
is_error: boolean;
num_turns: int;
session_id: string;
total_cost_usd: float;
}
// Emitted as the first message at the start of a conversation
| {
type: "system";
subtype: "init";
apiKeySource: string;
cwd: string;
session_id: string;
tools: string[];
mcp_servers: {
name: string;
status: string;
}[];
model: string;
permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
};
์ด๋ฌํ ์ ํ์ ๊ณง JSONSchema ํธํ ํ์์ผ๋ก ๊ฒ์๋ ์์ ์ ๋๋ค. Claude Code ๊ธฐ๋ณธ ํจํค์ง์๋ ์ด ํ์์ ํ๊ดด์ ๋ณ๊ฒฝ ์ฌํญ์ ์ ๋ฌํ๊ธฐ ์ํด Semantic Versioning์ ์ฌ์ฉํ๊ณ ์์ต๋๋ค.
Message ๋ฐ MessageParam ํ์
Message
๋ฐ MessageParam
ํ์
์ Anthropic SDK์์ ์ฌ์ฉํ ์ ์์ต๋๋ค. ์๋ฅผ ๋ค์ด, Anthropic TypeScript ๋ฐ Python SDK๋ฅผ ์ฐธ์กฐํ์ญ์์ค.
์ ๋ ฅ ํ์
SDK๋ ์ฌ๋ฌ ์ ๋ ฅ ํ์์ ์ง์ํฉ๋๋ค.
ํ ์คํธ ์ ๋ ฅ (๊ธฐ๋ณธ๊ฐ)
์ ๋ ฅ ํ ์คํธ๋ ์ธ์๋ก ์ ๊ณต๋ ์ ์์ต๋๋ค.
$ claude -p "Explain this code"
๋๋ ์ ๋ ฅ ํ ์คํธ๋ stdin์ ํตํด ํ์ดํ๋ ์ ์์ต๋๋ค.
$ echo "Explain this code" | claude -p
์คํธ๋ฆฌ๋ฐ JSON ์ ๋ ฅ
๊ฐ ๋ฉ์์ง๊ฐ ์ฌ์ฉ์ ํด์ ๋ํ๋ด๋ ๋ฉ์์ง ์คํธ๋ฆผ์ด stdin
์ ํตํด ์ ๊ณต๋ฉ๋๋ค. ์ด๋ฅผ ํตํด claude
๋ฐ์ด๋๋ฆฌ๋ฅผ ๋ค์ ์์ํ์ง ์๊ณ ๋ ์ฌ๋ฌ ํด์ ๋ํ๋ฅผ ํ ์ ์์ผ๋ฉฐ, ๋ชจ๋ธ์ด ์์ฒญ์ ์ฒ๋ฆฌํ๋ ๋์ ๋ชจ๋ธ์ ์ง์นจ์ ์ ๊ณตํ ์ ์์ต๋๋ค. ๊ฐ ๋ฉ์์ง๋ ์ถ๋ ฅ ๋ฉ์์ง ์คํค๋ง์ ๋์ผํ ํ์์ JSON โ์ฌ์ฉ์ ๋ฉ์์งโ ๊ฐ์ฒด์
๋๋ค. ๋ฉ์์ง๋ ๊ฐ ์
๋ ฅ ๋ผ์ธ์ด ์์ ํ JSON ๊ฐ์ฒด์ธ jsonl ํ์์ผ๋ก ํฌ๋งท๋ฉ๋๋ค. ์คํธ๋ฆฌ๋ฐ JSON ์
๋ ฅ์๋ -p
๋ฐ --output-format stream-json
์ด ํ์ํฉ๋๋ค. ํ์ฌ๋ ํ
์คํธ ์ ์ฉ ์ฌ์ฉ์ ๋ฉ์์ง๋ก ์ ํ๋ฉ๋๋ค.
$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose
์์
๊ฐ๋จํ ์คํฌ๋ฆฝํธ ํตํฉ
#!/bin/bash
# Simple function to run Claude and check exit code
run_claude() {
local prompt="$1"
local output_format="${2:-text}"
if claude -p "$prompt" --output-format "$output_format"; then
echo "Success!"
else
echo "Error: Claude failed with exit code $?" >&2
return 1
fi
}
# Usage examples
run_claude "Write a Python function to read CSV files"
run_claude "Optimize this database query" "json"
Claude๋ก ํ์ผ ์ฒ๋ฆฌ
# Process a file through Claude
$ cat mycode.py | claude -p "Review this code for bugs"
# Process multiple files
$ for file in *.js; do
echo "Processing $file..."
claude -p "Add JSDoc comments to this file:" < "$file" > "${file}.documented"
done
# Use Claude in a pipeline
$ grep -l "TODO" *.py | while read file; do
claude -p "Fix all TODO items in this file" < "$file"
done
์ธ์ ๊ด๋ฆฌ
# Start a session and capture the session ID
$ claude -p "Initialize a new project" --output-format json | jq -r '.session_id' > session.txt
# Continue with the same session
$ claude -p --resume "$(cat session.txt)" "Add unit tests"
๋ชจ๋ฒ ์ฌ๋ก
- JSON ์ถ๋ ฅ ํ์ ์ฌ์ฉ์ ์๋ต์ ํ๋ก๊ทธ๋๋ฐ ๋ฐฉ์์ผ๋ก ํ์ฑํ๋ ๋ฐ ์ ์ฉํฉ๋๋ค.
# Parse JSON response with jq result=$(claude -p "Generate code" --output-format json) code=$(echo "$result" | jq -r '.result') cost=$(echo "$result" | jq -r '.cost_usd')
- ์ค๋ฅ๋ฅผ ์ ์ฐํ๊ฒ ์ฒ๋ฆฌํ์ญ์์ค. ์ข
๋ฃ ์ฝ๋์ stderr๋ฅผ ํ์ธํ์ญ์์ค.
if ! claude -p "$prompt" 2>error.log; then echo "Error occurred:" >&2 cat error.log >&2 exit 1 fi
- ๋ค์ค ํด ๋ํ์์ ์ปจํ ์คํธ ์ ์ง๋ฅผ ์ํด ์ธ์ ๊ด๋ฆฌ๋ฅผ ์ฌ์ฉํ์ญ์์ค.
- ์ฅ๊ธฐ ์คํ ์์
์ ๋ํด ํ์์์์ ๊ณ ๋ คํ์ญ์์ค.
timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
- ์ฌ๋ฌ ์์ฒญ์ ์ํํ ๋ ์ง์ฐ์ ์ถ๊ฐํ์ฌ ์๋ ์ ํ์ ์ค์ํ์ญ์์ค.
์ค์ ์์ฉ ํ๋ก๊ทธ๋จ
Claude Code SDK๋ ๊ฐ๋ฐ ์ํฌํ๋ก์ ๊ฐ๋ ฅํ๊ฒ ํตํฉ๋ ์ ์๋๋ก ํฉ๋๋ค. ์ฃผ๋ชฉํ ๋งํ ์์ ์ค ํ๋๋ SDK๋ฅผ ์ฌ์ฉํ์ฌ GitHub ์ํฌํ๋ก ๋ด์์ ์๋ํ๋ ์ฝ๋ ๊ฒํ , PR ์์ฑ ๋ฐ ์ด์ ๋ถ๋ฅ ๊ธฐ๋ฅ์ ์ ๊ณตํ๋ Claude Code GitHub Actions์ ๋๋ค.
๊ด๋ จ ๋ฆฌ์์ค
- CLI ์ฌ์ฉ๋ฒ ๋ฐ ์ ์ด - ์ ์ฒด CLI ๋ฌธ์์ ๋๋ค.
- GitHub Actions ํตํฉ - Claude๋ก GitHub ์ํฌํ๋ก๋ฅผ ์๋ํํ์ญ์์ค.
- ์ผ๋ฐ์ ์ธ ์ํฌํ๋ก - ์ผ๋ฐ์ ์ธ ์ฌ์ฉ ์ฌ๋ก์ ๋ํ ๋จ๊ณ๋ณ ๊ฐ์ด๋์ ๋๋ค.