만약 코딩 에이전트(coding agents)에 대한 당신의 경험이 "설치하고 채팅하는 것"뿐이라면, 당신은 아직 진정한 첫 성공을 경험하지 못한 것입니다. 팀원들에게 스크린샷을 찍어 보여줄 수 있는 그런 성공 말입니다. 대부분의 입문 게시물은 "한 번 대화해 보았다" 수준에서 멈추며, 이는 해당 도구가 실제로 실제 저장소(repository)를 다룰 수 있는지 여부를 알려주지 않습니다. 이 가이드는 다른 기준을 통해 그 문제를 해결합니다.

SolonCode는 Java로 작성된 오픈 소스 코딩 에이전트로, Solon AI 프레임워크를 기반으로 구축되었으며 Java 8부터 Java 26까지 실행되도록 설계되었습니다. 한 가지 솔직한 주의사항을 미리 말씀드리자면, 이 도구의 프롬프트(prompt) 시스템은 중국어 우선 상호작용을 중심으로 구축되어 있습니다(공식 문서에서는 중국어 프롬프트를 다룰 수 없다면 권장하지 않는다고 명시되어 있습니다). 이는 중국어를 사용하는 팀이나, 자신만의 게이트웨이(gateway)에서 실행할 수 있는 모델 불가지론적(model-agnostic) 에이전트를 원하는 개발자들에게 흥미로운 선택지가 됩니다. 아래의 모든 내용은 SolonCode v2026.8.3 기준 공식 문서를 바탕으로 검증되었습니다.

여기서 말하는 "첫 성공"의 실제 의미

대부분의 짧은 튜토리얼은 다음과 같은 세 가지 실패 유형을 남깁니다:

• 모델이 연결되지 않으며, 이것이 실패인지 설정 오류인지 알 수 없음.
• 채팅은 했지만, 에이전트가 실제 파일을 수정하지 않아 여전히 신뢰할 수 없음.
• 무언가 고장 났지만 API 키, 프록시(proxy), 또는 워크스페이스 경로 중 무엇을 확인해야 할지 모름.

따라서 이 가이드는 세 가지 구체적인 통과 기준인 L1, L2, L3를 설정하고 고정된 경로를 제공합니다: 설치 → Web UI에서 모델 설정 → 작은 리뷰 가능한 변경 사항 반영하기. 목표는 15분 만에 SolonCode의 모든 것을 배우는 것이 아니라, 동료에게 설명할 수 있는 스크린샷을 찍을 만한 첫 번째 성공을 거두는 것입니다.

사전 요구 사항 (2분 자가 점검)

SolonCode는 특정 벤더를 번들로 포함하거나 종속되지 않습니다. 사용자가 직접 모델을 가져오거나 (BYOK, Bring Your Own Model), 내부 게이트웨이를 지정해야 합니다. 작동하는 모델 설정이 없다면 프로세스는 시작되더라도 진정한 첫 번째 성공이라고 할 수 없습니다.

권장 사항 (필수 사항은 아님): Git (Web UI에서 diff를 확인하는 데 도움이 됨), 작은 실제 프로젝트 디렉토리 (실행 디렉토리가 워크스페이스가 됨), 안정적인 네트워크 및 올바른 프록시 (Proxy) 설정.

설치: 명령어 한 줄, 그 후 버전 확인

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

동일한 설치 명령어를 다시 실행하면 설정 및 정의 파일을 유지하면서 프로그램을 업데이트합니다. 프로그램 및 사용자 수준의 설정은 기본적으로 ~/.soloncode/에 저장됩니다 (Windows의 경우 홈 디렉토리 아래의 .soloncode).

최소 성공 확인:

soloncode version

버전 문자열이 출력되면 계속 진행해도 좋습니다. 만약 command not found 오류가 발생한다면: 설치 프로그램을 다시 실행하고, soloncode가 PATH에 포함되어 있는지 확인한 후, 새 터미널 창을 여세요 (PATH 변경 사항은 종종 새로운 셸이 필요합니다).

오프라인 또는 인트라넷 설치를 위한 공식 경로는 다음과 같습니다: 네트워크가 연결된 PC에서 Gitee Releases로부터 soloncode-cli-bin-*.tar.gz를 다운로드하여 복사한 뒤, 압축을 풀고 install.sh 또는 install.ps1을 실행하십시오. 첫 번째 성공을 위해서는 먼저 온라인 상태에서 진행하는 것을 권장합니다.

Web UI에서 첫 번째 모델 설정하기

신규 사용자를 위해 공식적으로 권장되는 방법은 Web 설정 페이지를 사용하는 것입니다. 첫날부터 설정 파일을 직접 편집할 필요는 없습니다.

soloncode web 0

web 명령어 동작 방식: soloncode web은 기본 포트 4808을 사용합니다. soloncode web 0은 사용 가능한 포트를 자동으로 선택합니다 (4808 포트가 이미 사용 중일 때 유용합니다). soloncode web 1212는 특정 포트를 바인딩(bind)합니다. 터미널에는 Web interface: http://localhost:xxxxx/와 같은 메시지가 출력됩니다.

그다음 단계:

1. Web UI에서 Settings → LLM (또는 이에 상응하는 메뉴)을 엽니다.
2. 최소한 다음 항목을 포함하여 모델을 추가 (Add a model) 합니다: API URL (apiUrl), API 키 (제공업체에서 요구하는 경우), 그리고 모델 이름 (제공업체의 콘솔에 표시된 것과 정확히 일치해야 함).
3. "Test connection" 버튼을 사용합니다. 공식 문서에서도 이 기능이 작동함을 강조합니다.
4. 모델이 활성화 (enabled) 되어 있고 대화 모델 목록에 나타나는지 확인합니다.

설정은 settings.json에 저장됩니다: 사용자 수준(user-level) 설정은 ~/.soloncode/settings.json에 저장되며 (모든 프로젝트에서 공유됨), 워크스페이스 수준(workspace-level) 설정은 .soloncode/settings.json에 저장됩니다 (프로젝트별로 적용됨). 워크스페이스 설정은 사용자 수준 설정 이후에 읽히며, 이를 덮어쓰거나 확장할 수 있습니다. 보안 주의 사항: 키는 비밀 정보입니다. settings.json을 절대 Git에 커밋하지 마세요. 팀 환경에서는 시크릿 매니저(secret manager)를 사용하거나 개발자별 로컬 설정을 사용하십시오.

모델 설정 성공 체크리스트:

• 연결 테스트(Test connection) 통과
• "hello" 메시지에 대해 모델이 정상적인 응답을 보냄 (타임아웃 / 401 / 빈 응답이 아님)
• UI 제목 근처에 현재 모델 이름이 표시됨 (예: Model:deepseek-v4-flash — 설정한 이름)

이제야 비로소 "설치가 완료되어 대화가 가능한" 상태가 되었습니다. 이것이 아직 코딩의 성공을 의미하는 것은 아닙니다.

프로젝트 진입 (워크스페이스 = 실행 디렉토리)

공식 문서에서는 프로젝트 루트(root) 내부에서 시작하는 것을 권장합니다. 실행 디렉토리가 현재 워크스페이스(workspace)가 됩니다.

cd /path/to/your-project
soloncode web 0
# 또는
...

아직 프로젝트가 없나요? 빈 디렉토리에서도 대화 및 파일 생성을 탐색할 수 있지만, L2/L3 단계에서는 실제 리포지토리(repository)를 사용하는 것이 강력하게 권장됩니다. 그렇지 않으면 당신의 "데모"는 설득력이 떨어집니다. CLI가 시작되면 팁(tips) 라인은 다음과 같이 표시됩니다:

Tips: (esc) interrupt | /(tab) command | $(tab) skill | @(tab) agent

esc는 중단(interrupt) 기능을 수행하며, 명령어(commands), 스킬(skills), 하위 에이전트(subagents)는 탭(tab) 자동 완성 기능을 지원합니다. 첫 번째 성공을 거두기에는 자연어만으로도 충분합니다.

3단계 작업: L1 → L2 → L3

권장 시간 배분 (총 약 15분 소요, 모델 속도에 따라 다름): L1 약 3분, L2 57분, L3 57분. 모델이 느리거나 저장소(repo)가 큰 경우, 리뷰를 건너뛰고 L3로 서두르기보다는 L2를 철저히 수행하세요.

L1 — 인사 및 프로젝트 스캔

다음 내용을 전송하세요 (중국어로 — 이는 제품의 퍼스트 클래스 상호작용 언어입니다):

请先阅读当前项目结构，告诉我：
1）这是什么技术栈；
2）构建命令和测试命令分别可能是什么；
...

만약 프로젝트에 아직 CODE.md가 없다면, 공식 퀵 스타트(quick start)에서는 다음과 같이 계속할 것을 권장합니다:

请根据当前项目生成 .soloncode/CODE.md，包含构建命令、测试命令和代码修改注意事项。

L1 통과 기준 (모두 충족해야 함):

• 기술 스택(tech-stack) 설명이 저장소와 대략적으로 일치함 (정직하게 "추가 확인 필요"라고 답하는 것은 허용됨)
• 빌드/테스트 진입점(entry points)이 명시되거나 추론됨 (또는 찾을 수 없다고 정직하게 보고됨)
• 파일 변경을 요청하지 않았을 때, git status에서 예상치 못한 변경된 파일(dirty files)이 나타나지 않음

일반적인 L1 실패 사례: 프로젝트 루트(root)에서 시작하지 않음; 모델 설정 오류; 빈 저장소 또는 읽기 권한 없음.

L2 — 작은 변경 + Diff 설명 (첫 번째 "시연 가능한" 단계)

작업 A (문서, 가장 낮은 리스크):

请帮我检查 README 中是否有过时的安装说明，只修改文档，不改业务代码。
完成后：
1）列出改了哪些文件；
...

작업 B (코드, 여전히 작은 규모):

请新增一个简单的健康检查接口（或补全已有 health 相关说明），范围尽量小。
限制：
- 不要做大范围重构；
...

L2 통과 기준:

• 지칭 가능한 파일 변경 사항이 존재함 (Web Git Diff 또는 git diff에서 확인 가능)
• 에이전트(agent)가 무엇이 왜 바뀌었는지 자연어로 설명함
• 사용자가 직접 Diff를 스캔함 — 키(keys) 노출 없음, 대규모의 무관한 포맷팅 없음, 실수로 삭제된 내용 없음
• 이 변경 사항을 동료에게 한 문장으로 설명할 수 있음 (이것이 "시연 가능한" 수준임)

인간 검토 체크리스트 (필수, 30초~2분): 변경 사항이 허용된 범위를 초과했는가? API 키, 인트라넷 주소 또는 비밀번호가 포함되었는가? Lockfiles (잠금 파일) 또는 생성된 아티팩트 (artifacts)가 수정되었는가? 검증 단계를 직접 실행할 수 있는가?

이 지점에서 SolonCode의 가치가 나타나기 시작합니다. SolonCode는 구현을 진전시키고, 당신은 경계와 병합 (merge) 결정을 수호합니다.

L3 — 제약된 작은 기능 (반드시 검토 가능해야 함)

L2를 통과한 후에만 수행합니다. 프롬프트 템플릿에는 공식 문서에서 강조하는 네 가지 요소인 **목표 (goal), 범위 (scope), 제약 사항 (constraints), 검증 (verification)**이 포함되어 있습니다.

목표: {산출물의 동작을 설명하는 한 문장, 예: 사용자 모듈에 이메일 기반 조회용 읽기 전용 인터페이스 추가}
범위: {패키지명/디렉토리} 하위의 파일만 수정 가능; 문서는 필요할 때만 README의 작은 섹션을 업데이트함.
제약 사항:
...

L3 통과 기준:

• 네 가지 산출물이 모두 존재함 (목록 / 설명 / 명령 결과 / 리스크)
• Diff (차이점)를 제삼자가 검토할 수 있음 (정체불명의 대규모 재배치 없음)
• 검증 명령이 실행되었거나, 차단 요소 (blocker)가 신뢰할 수 있음
• 당신이 명시적으로 결정함: 수락 / 부분 수락 / 롤백(roll back) — 결정권은 인간에게 있음

L3에 명시적으로 포함되어서는 안 되는 것: 사이트 전체 재작성, 한 번에 수행하는 다중 서비스 마이그레이션, 테스트 없는 "부수 효과로서의 리팩터링 (refactoring)", 운영 데이터 작업, 권한 상승, 키 로테이션(key rotation) — 그리고 절대로 "한 번의 대화"를 "검토 없이 병합 가능"으로 간주해서는 안 됩니다.

스크린샷 체크리스트 (팀 채널용)

형용사로 가득 찬 한 단락보다 4~6개의 스크린샷이 더 효과적입니다:

상위 10가지 실패 사례 및 우선 확인 사항

공식 문서의 디버깅 힌트: 워크스페이스 하위의 디스크 로그 **.soloncode/logs/**를 확인하세요; 문서: logs & troubleshooting.

안전 관련 주의 사항: 설정에는 hitlEnabled와 같은 HITL (Human-in-the-loop, 인간 참여형) 스위치가 존재합니다. 첫 성공을 거두는 동안에는 기본적으로 보수적인 태도를 유지하세요. 프로덕션 리포지토리(production repo)에서 속도를 높이기 위해 안전 관련 제한 사항을 함부로 비활성화하지 마십시오.

첫 성공 이후: 딱 두 가지의 단계적 절차

Loop / 멀티 에이전트 (multi-agent) / IM 바인딩 (IM binding)으로 바로 뛰어들지 마세요. 가장 작은 다음 루프는 다음과 같습니다:

1. .soloncode/AGENTS.md에 10줄 내외의 프로젝트 AGENTS.md 작성하기 (사용자 레벨의 ~/.soloncode/AGENTS.md보다 워크스페이스 레벨이 우선됩니다). 최소한의 복사-붙여넣기 템플릿:

# 本项目 Agent 规约（精简）

## 必须
...

공식 권장 사항: 컨텍스트 (context)를 과도하게 점유하지 않도록 짧게 유지하세요. 정체성, 경계, 그리고 워크플로우 (workflow)를 명확하게 기술하십시오.

2. 정확히 하나의 스킬 (Skill) 설치하기. 웹의 Settings → Skill Market을 통하거나 (탐색, 설명 읽기, 그 후 글로벌 또는 워크스페이스 풀에 설치), 수동으로 설치할 수 있습니다: SKILL.md가 포함된 디렉토리를 ~/.soloncode/skills/ 또는 .soloncode/skills/에 넣으세요. 다음 명령으로 실행합니다:

请使用 {技能名} 按它的规约帮我完成 {一件具体事}。

CLI 스킬 완성: $(tab). 원칙: 설치하기 전에 SKILL.md의 시나리오와 권한을 읽으십시오. 스킬이 많다고 해서 에이전트가 더 강력해지는 것은 아닙니다. 관련성 있는 스킬이 많을수록 에이전트가 더 강력해집니다. 공식 스킬 문서: agent skills.

경계: 무엇이 '첫 성공'이 아닌지, 그리고 언제 멈춰야 하는지

아직 첫 성공이 아닌 경우: 웹 페이지를 열기만 했고 모델 테스트가 실패한 경우; 채팅만 했을 뿐 실제 리포지토리에서 리뷰 가능한 디프 (diff)를 생성하지 못한 경우; 디프는 생성했으나 이를 확인하지 않았고 설명할 수 없는 경우.

다음의 경우 오늘은 멈추세요: 대상이 테스트가 없고 리뷰할 사람이 없는 프로덕션 메인 브랜치(production main branch)인 경우; 요청 사항이 아키텍처 레벨의 재작성(architecture-level rewrite)인 경우; 또는 정당한 모델 접근 경로(계정 / 게이트웨이 / 컴플라이언스)가 없는 경우.

SolonCode는 위임 가능한 코딩 에이전트 (delegatable coding agent)이지, 자동 면책 기계 (auto-disclaimer machine)가 아닙니다. 사람이 방향성, 경계, 그리고 머지 (merge)를 소유하며, 에이전트는 그 경계 안에서 전진합니다.

15분 경로 (한 페이지 요약)

1. java -version            # 8 이상
2. curl ...setup.sh | bash  # 또는 irm ...setup.ps1 | iex
3. soloncode version
...

이것이 중요한 이유

첫 번째 성공은 AI에 대한 믿음에 관한 것이 아닙니다. 그것은 네 가지 실질적인 요소에 관한 것입니다: 실제 환경 (PATH에 설정된 JDK + 명령어), 실제 모델 (양식만 저장하지 말고 연결을 테스트할 것), 실제 작업 (프로젝트 루트 내에서 리뷰 가능한 작은 변경 사항), 그리고 실제 리뷰 (사람이 diff를 읽고 머지 버튼을 클릭하는 것)입니다.

L2 단계를 안정적으로 반복할 수 있게 되면, SolonCode는 단순히 "또 하나의 채팅창"이 아니라 귀하의 워크플로우에 디지털 직원을 온보딩 (onboarding)하는 첫날이 됩니다. 다음 단계들 — 모델 라우팅 (model routing) 및 비용 (시리즈 B2), AGENTS.md로 사양을 코드화하기 (시리즈 D3), 또는 IM을 통한 원격 위임 (시리즈 C2) —은 모두 위의 통과 기준을 바탕으로 구축됩니다.

지금 바로 시도해보세요: 한 페이지 경로의 처음 8단계를 실행하고 L2 diff 스크린샷을 보관하세요. 그것이 SolonCode가 여러분에게 줄 수 있는 가장 정직한 매뉴얼입니다.