대부분의 코딩 에이전트(coding agents)는 첫 대화를 나누기 위해 많은 노력을 요구합니다. 바이너리를 설치한 다음, 설정 파일(config file)을 찾아 헤매야 하고, 그 설정 파일이 정확하게 입력해야 하는 프로바이더 이름(provider name), 마지막 경로 세그먼트(trailing path segment)가 필요할 수도 있고 아닐 수도 있는 베이스 URL(base URL), 그리고 텍스트 에디터에 붙여넣으면서 뒤에 공백이 남지 않았기를 기도해야 하는 키(key)를 요구한다는 사실을 알게 됩니다.

SolonCode는 이를 건너뜁니다. 웹 모드(web mode)로 시작하면 브라우저가 열리고, 설정 패널(settings panel)에서 모델을 추가하면 됩니다. 엔드포인트(endpoint)를 붙여넣고, 키(key)를 붙여넣고, 테스트(test)를 누른 뒤 저장하세요. 채팅 영역이 즉시 새로운 모델을 인식합니다. 내부적으로는 settings.json 파일이 존재하며 궁금하다면 읽어볼 수 있지만, 첫 번째 작업을 수행하는 과정에서 이 파일을 열 필요는 전혀 없습니다.

실제로 보게 될 화면들과 함께 전체 과정을 소개합니다.

시작하기 전에

두 가지 사항:

• Java 8 이상. SolonCode는 Java 8부터 Java 26까지 실행되므로, 프로젝트가 이미 빌드할 때 사용하는 JDK라면 거의 확실히 문제없습니다.
• 접근 가능한 하나의 모델 엔드포인트 (model endpoint). OpenAI, Anthropic, Gemini, Ollama 또는 호환 가능한 형식을 사용하는 것이라면 무엇이든 가능합니다.

선택 사항(나중에 관련 기능을 사용하고 싶은 경우에만 해당): Node.js (일부 MCP 서버, Skills 및 브라우저 유형 도구용), Git (웹 UI에서 diff 및 staging을 보여주기 위함), 그리고 언어 서버 (LSP 기반의 코드 이해를 위함). 이 중 어느 것도 첫 실행을 방해하지 않습니다.

설치:

# macOS / Linux / Harmony PC
curl -fsSL https://solon.noear.org/soloncode/setup.sh | bash

# Windows PowerShell
irm https://solon.noear.org/soloncode/setup.ps1 | iex

나중에 동일한 명령어를 다시 실행하는 것이 업데이트 방법입니다. 설치 프로그램은 프로그램 파일들을 갱신하며, 이미 구성한 내용(settings.json, AGENTS.md 등)을 최대한 보존하기 위해 최선을 다합니다.

설치 확인:

soloncode version
# SolonCode v2026.8.4

웹 모드 시작

실제로 작업하려는 프로젝트로 이동하세요. 실행한 디렉터리가 워크스페이스 (workspace)가 되며, 이는 나중에 스코핑 (scoping)에 중요하므로 홈 디렉터리에서 바로 실행하기보다는 먼저 cd를 사용하세요.

cd your-project
soloncode web 0

포트를 선택하는 세 가지 방법:

web 0은 여러 프로젝트를 열어두었을 때 사용하기 좋은 방법입니다. 잊고 있던 인스턴스와 충돌할 일이 없기 때문입니다. 브라우저 탭에는 워크스페이스 이름과 경로가 표시되어, 네 개의 열린 탭을 구분할 수 있습니다.

터미널에 선택된 주소가 출력됩니다:

SolonCode v2026.8.4 PID-4131 Model:your-model
/path/to/your-project
Web interface: http://localhost:1212/

브라우저가 자동으로 열립니다. 만약 자동으로 열리지 않는다면 — 원격 서버, 헤드리스 (headless) 환경, 혹은 협조적이지 않은 OS인 경우 — 해당 출력물에서 주소를 복사하세요.

접속하면 환영 화면이 나타납니다: 중앙에는 입력창이, 오른쪽에는 워크스페이스 파일 트리 (file tree)가, 왼쪽에는 대화 컨트롤 (conversation controls)이 있으며, 입력창 아래에는 현재 모델이 표시됩니다.

[

첫 번째 단계: 언어 설정하기

왼쪽 사이드바 (left rail)에서 Settings를 클릭하면, General 항목 아래의 첫 번째 카드가 Display Language입니다. 기본값은 _Follow system default_로 설정되어 있으며, 이는 UI가 운영체제 (OS)의 언어를 따른다는 의미입니다.

[

목록에는 23개의 로케일 (locales)이 있습니다. 원하는 언어를 선택하면 재시작이나 새로고침 없이 즉시 인터페이스가 다시 렌더링 (re-renders)됩니다. 메뉴, 섹션 이름, 버튼, 플레이스홀더 (placeholder) 텍스트 등 모든 것이 변경됩니다.

드롭다운 메뉴가 알려주지 않는, 알아두면 좋은 두 가지 사항이 있습니다:

설정은 세션 단위로 적용됩니다. 언어를 선택하면 즉시 적용되지만, 페이지를 새로고침하면 다시 시스템 기본값 따르기 (Follow system default) 상태로 돌아갑니다. 만약 사용 중인 OS의 로캘 (locale)이 원하는 설정과 이미 일치한다면 이를 전혀 느끼지 못할 것입니다. 그렇지 않다면, 새로고침 후에 다시 선택해야 할 것입니다.

이 설정은 UI를 변경할 뿐, 에이전트 (agent)를 변경하지 않습니다. 표시 언어 (Display Language)는 크롬 (chrome, 인터페이스 요소)을 제어합니다. 모델이 답변하는 언어는 모델로부터 나오며, 모델은 다른 언어로 작성된 프롬프트 (prompt)에 대해 기꺼이 한 가지 언어로 답변할 것입니다. 영어 답변을 원한다면, 영어로 답변해 달라고 요청하세요:

Reply in English. <당신의 실제 요청 내용>

또는 AGENTS.md에 한 번만 작성하여 반복하지 않도록 하세요.

나중에 다시 확인하실 수 있도록, 일반 (General) 설정의 나머지 항목들을 나열해 둡니다: 대화 전략 (Conversation Strategy), 샌드박스 모드 (Sandbox Mode), 메모리 (Memory), 실패 시 재시도 (Retry on Failure), 그리고 외관 (Appearance).

설정 패널

측면에 9개의 섹션이 있습니다:

General · Agents · Mounts · Skills · Providers · Models · MCP Servers · OpenAPI Servers · LSP Servers

Models를 선택하세요.

누군가 말해주지 않으면 낭패를 볼 수 있는 작은 주의사항 하나: Esc 키를 누르면 현재 열려 있는 양식 (form)뿐만 아니라 설정 패널 전체가 닫힙니다. 양식에서 나가고 싶을 때는 패널 자체의 뒤로 가기 (Back) 버튼을 사용하세요.

첫 번째 모델 추가하기

Models → + Add Model. 이는 팝업 대화 상자가 아니라 패널 내부의 전체 페이지로 열립니다:

• Name (이름) — 모델 선택기(model picker)에 표시되는 방식입니다. 자유 텍스트 형식이므로 한눈에 알아볼 수 있는 이름을 지정하세요.
• Scope (범위) — User (Global, 사용자 전역) 및 Workspace (Local, 워크스페이스 로컬) 두 가지 버튼이 있습니다. 이에 대한 자세한 내용은 아래에서 설명합니다.
• URL mode (URL 모드) — 드롭다운 메뉴이며, 기본값은 _Full URL (auto-detect, 전체 URL 자동 감지)_입니다. 대안으로는 OpenAI Chat Completions, OpenAI Responses, Anthropic을 위한 BaseUrl 모드와 Gemini 및 Ollama 전용 항목이 있습니다. 자동 감지는 일반적인 경우를 처리하며, 엔드포인트가 전체 completions URL이 아닌 경우 특정 모드를 선택하세요.
• API URL — 플레이스홀더(placeholder)에 https://api.deepseek.com/v1/chat/completions와 같이 원하는 형식이 표시됩니다.
• API Key (API 키) — sk-... 형식이며, 표시/숨기기 토글이 있습니다.
• Model (모델) — 제공업체의 모델 식별자(identifier)입니다.
• Context length (컨텍스트 길이) — 일반적인 크기들이 포함된 드롭다운 메뉴입니다.
• Timeout (타임아웃) — 기본값은 120초입니다.
• Extra options (추가 옵션) — temperature, top_p 또는 추론 플래그(reasoning flags)와 같은 항목을 위한 JSON 필드이며, Format JSON (JSON 형식화) 버튼이 있습니다. 비워두는 것도 아주 좋은 방법입니다.
• Set as default model (기본 모델로 설정) — 체크박스입니다.

로컬 Ollama 인스턴스에 맞춰 입력한 모습:

그다음 사람들이 건너뛰는 부분: Save (저장)를 누르기 전에 반드시 Test Connection (연결 테스트)을 누르세요.

추가되었지만 도달할 수 없는 모델은 작동하는 모델과 동일하게 보입니다. 첫 번째 작업이 실행 도중 실패하고, 문제가 키 때문인지, URL 때문인지, 아니면 프록시(proxy) 때문인지 파악하기 위해 로그를 읽기 전까지는 말이죠. 테스트 버튼은 Save 바로 옆에 있습니다. 여기서 10초만 투자하면 혼란의 범주 자체를 없앨 수 있습니다.

저장한 후에는 채팅 영역의 모델 목록이 재시작 없이도 이에 맞춰 새로고침됩니다. 목록이 길어진 경우, 선택기(picker)에서 검색 필터링을 지원하므로 스크롤하는 대신 일부 문자열을 입력하면 됩니다.

Global or workspace (전역 또는 워크스페이스)

양식의 범위(scope) 버튼은 모델이 어떤 파일에 저장될지를 결정합니다:

SolonCode는 사용자 수준 (user-level) 파일을 먼저 읽은 다음 워크스페이스 파일을 읽으며, 워크스페이스 설정이 이전에 발견된 내용을 덮어쓰거나 보완합니다.

워크스페이스 범위 (Workspace scope)는 잠시 생각해 볼 가치가 있는 2차적인 효과를 가집니다. 해당 파일은 프로젝트 디렉토리 내에 위치하므로 커밋 (commit)할 수 있습니다. 그런 방식으로 팀원들과 엔드포인트 (endpoint) 및 모델 선택 사항을 공유하는 것은 진정으로 유용합니다. 하지만 그런 방식으로 API 키를 공유하는 것은 유용하지 않습니다. git add를 하기 전에 당신이 무엇을 하고 있는지 결정하십시오.

하나의 키로 여러 모델을 사용하는 경우의 프로바이더 (Providers)

동일한 엔드포인트에 대해 두 번째 또는 세 번째 모델을 추가하는 경우, 프로바이더 (Providers) 섹션에서 작업하는 것이 더 좋습니다. 이곳은 벤더 설정 (vendor config) — API 주소, 키 — 을 하나의 항목으로 관리하며, 프로바이더별로 추가, 수정, 활성화/비활성화를 수행할 수 있습니다.

이것에 신경 써야 하는 이유는 설정보다는 유지보수 때문입니다. 키가 교체될 때, 각자 자신의 복사본을 기억하는 네 개의 모델 항목이 아니라 한 곳에서 변경하기를 원할 것입니다. 엔드포인트를 이동할 때도 마찬가지입니다. 프로바이더를 한 번 설정하고, 모델들이 이를 가리키도록 하십시오.

첫 번째 대화

코드 변경부터 시작하지 마십시오. 질문부터 시작하십시오. 왜냐하면 그 답변이 모델이 실제로 당신의 리포지토리 (repo)를 보고 있는지 알려주기 때문입니다:

Reply in English. What kind of project is this directory?
Check the build file and source layout before answering.

위의 도구 추적(tool trace)을 확인하세요: ls 명령, pom.xml에 대한 glob 검색, 해당 파일 읽기, 그리고 src 디렉터리에 대한 재귀 목록화입니다. 이 에이전트는 말하기 전에 먼저 살펴봤습니다. 그리고 보고한 내용은 스켈레톤은 존재하지만 — 부모 POM(parent POM), 웹 의존성 하나, 표준 Maven 레이아웃 — 소스 코드도 없고, app.yml도 없고, 테스트 코드도 없어서 실제로 작성된 것은 아무것도 아니라는 것이었습니다.

이것이 바로 당신이 확인해야 할 신호입니다. 만약 어떤 에이전트가 작동하는 애플리케이션을 설명했다고 해도, 실제 저장소(repo)에서는 그를 믿을 수 없는 에이전트일 것입니다. 푸터(footer)도 주목하세요: 토큰 개수, 경과 시간, 그리고 실행 컨텍스트 사용량입니다. 이를 통해 한 번의 상호작용(turn)이 얼마나 비용이 들었는지 알 수 있습니다.

연결을 완료했다면, 에이전트가 작업할 기반 지식을 제공해야 합니다:

Generate .soloncode/CODE.md for this project, including build commands,
test commands, and notes on what to be careful about when modifying code.

만약 이 파일이 이미 존재한다면, SolonCode는 그 안에 있는 내용을 선호합니다. 이것이 핵심입니다 — 이 파일은 저장소에 대한 엔지니어링 계약(engineering contract)과 같으며, 이를 문서화해 두면 매 세션마다 빌드 과정을 다시 설명할 필요가 없어집니다.

이제 범위가 좁은 작은 작업을 수행해 봅시다:

Check whether the install instructions in README are out of date.
Docs only, no code changes. Tell me what you changed when you're done.

작고 첫 번째 검토만으로도 충분합니다. 지금 테스트하는 것은 에이전트가 얼마나 인상적인 일을 할 수 있는지를 테스트하는 것이 아니라, 당신이 그 출력을 읽고 신뢰할 수 있는지를 테스트하는 것입니다.

더 큰 작업의 경우, 프롬프트에 네 가지 요소가 포함되어야 합니다:

Goal: fix the NPE in the user login endpoint.
Scope: only the user module.
Constraint: do not change the response structure.
...

목표(Goal), 범위(Scope), 제약 조건(Constraint), 검증(Verification). 마지막 요소가 겉보기보다 훨씬 중요합니다. 검증을 요청하는 것이