이 글은 Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle에 제출하는 글입니다.
ScopeGhost: Gemma 3를 활용한 로컬 우선 AI 범위 감사 도구 구축
프리랜서들이 불편한 논쟁 대신 검증된 증거로 '범위 확장(scope creep)'에 도전할 수 있다면 어떨까요?
클라이언트가 기능을 하나 더 요청합니다. 그러더니 또 다른 수정 사항을 요구하죠. 심지어 원래 계약에 포함되지 않았던 네이티브 모바일 애플리케이션까지요.
프리랜서 개발자나 소규모 소프트웨어 에이전시에게 이러한 요청들은 수익성 높은 프로젝트를 몇 주간의 무급 노동으로 변질시킬 수 있습니다.
저는 ScopeGhost라는 오픈소스, 로컬 우선 AI 범위 감사 도구를 만들었습니다. 이 도구는 개발자가 들어오는 클라이언트 요청을 합의된 프로젝트 범위와 비교하고, 계약상의 증거를 검증하며, 검토 가능한 변경 주문(change-order) 초안을 준비하도록 돕습니다.
흥미로운 부분은 단순히 LLM을 웹 인터페이스 뒤에 배치하는 것이 아닙니다. 모델 주변에 경계를 설계하여 그 결론이 확인될 수 있도록 엔지니어링한 것입니다.
1. 구축 내용
ScopeGhost는 고정된 범위의 프로젝트를 관리하는 프리랜서 소프트웨어 엔지니어, 독립 컨설턴트, 부티크 에이전시를 위해 설계되었습니다.
이는 프로젝트 요구사항과 클라이언트 커뮤니케이션을 기준선 계약 조항과 비교하고, 인간이 검토할 수 있는 구조화된 결과물을 생성합니다.
핵심 기능
- 범위 분류 (Scope classification): 요청을
IN_SCOPE, POTENTIALLY_OUT_OF_SCOPE, AMBIGUOUS, 또는 INSUFFICIENT_EVIDENCE로 분류합니다.
- 증거 연계 결과 (Evidence-linked findings): 평가 결과를 제공된 출처 발췌문 및 계약 조항과 연결합니다.
- 인용 검증 (Citation verification): 인용된 증거가 실제로 제공된 출처 텍스트에 존재하는지 확인합니다.
- 주제 관련성 보호 장치 (Topic-relevance safeguards): 무관한 제외 조항이 범위 외 분류를 정당화하는 데 사용되는 것을 방지하는 데 도움을 줍니다.
- 결정론적 금융 계산 (Deterministic financial calculations): 정수 센트 산술(integer-cent arithmetic)을 사용하여 예상 비용을 계산합니다.
- 변경 요청 워크플로우 (Change-order workflow): 변경 요청 초안을 사람이 검토하고 고객과 논의할 수 있도록 준비하는 데 도움을 줍니다.
- 로컬 모델 추론 (Local model inference): 핵심 추론 워크플로우를 위해 호스팅되는 LLM API를 요구하는 대신 Ollama를 통해 Gemma 3를 사용합니다.
누가 비용을 지불할 수 있을까?
대상 시장은 독립 개발자, 프리랜서 컨설턴트 및 소규모 소프트웨어 에이전시입니다.
잠재적인 비즈니스 모델에는 개인 구독, 감사당 가격 책정 또는 에이전시 플랜이 포함됩니다. 이들은 실제 사용자와 검증해야 하는 상업적 가설이며, 저는 고객 수요나 수익을 확립하지 않았습니다.
가치 제안은 간단합니다: 미지급 작업이 되기 전에 잠재적으로 범위 외인 작업을 식별하는 것을 더 쉽게 만듭니다.
2. 코드 및 프로젝트 링크
GitHub 저장소: https://github.com/suvendukungfu/ScopeGhost
라이선스: MIT
이 프로젝트는 Next.js, React, TypeScript, Tailwind CSS, SQLite, Zod, Ollama, Gemma 3, Vitest 및 Playwright를 사용합니다.
3. 제품 워크플로우
이 애플리케이션은 프로젝트 범위와 새로운 고객 요청을 받아 그 관계를 분석하고, 증거를 확인하며, 검토할 결과를 제시합니다.
flowchart TD
A[
목표는 법적 판단을 자동화하는 것이 아닙니다. 개발자에게 범위(scope)에 대한 대화를 시작할 수 있는, 더 명확하고 증거 기반의 출발점을 제공하는 것입니다.
## 4. 시스템 아키텍처
ScopeGhost는 확률론적 모델 해석과 결정론적 검증 및 영속성을 분리합니다.
flowchart TB
subgraph INPUT["입력 계층"]
A["계약 조항"]
...
이것은 아키텍처의 논리적인 보기입니다. 모델이 분석을 제안하면, 애플리케이션이 검증과 재무 계산에 대한 책임을 집니다.
## 5. 심층 분석: Gemma 3 4B 및 로컬 추론
ScopeGhost는 **Ollama를 통해 Google Gemma 3 4B (`gemma3:4b`)**를 사용합니다.
Gemma 3는 오픈 웨이트(open-weight) 모델 패밀리입니다. 4B 변형은 로컬 추론 및 구조화된 자연어 분석을 실험하는 개발자에게 실용적인 출발점을 제공합니다.
### 모델의 역할
Gemma 3는 클라이언트 요청을 해석하고, 범위 분류를 제안하며, 후보 증거를 식별하고, 애플리케이션이 검증할 수 있도록 구조화된 분석을 생성하는 데 도움을 줍니다.
이는 견적이 존재하는지, 조항이 제공되었는지, 또는 재무 계산이 정확한지에 대한 최종 권위 역할을 하지는 않습니다.
| 책임 | 구성 요소 |
| :--- | :--- |
| 자연어 요청 해석 | Gemma 3 4B |
| ... |
|### 추론 시퀀스
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
sequenceDiagram
actor User
participant UI as ScopeGhost UI
...
### 모델의 한계점
실제 추론 지연 시간 및 출력 품질은 하드웨어, 모델 버전, 프롬프트 길이, 추론 설정 및 입력 복잡도에 따라 달라집니다.
보고된 통합 스위트 테스트는 실제 로컬 추론을 사용하여 특정 시나리오를 테스트합니다. 네 가지 통합 테스트만으로는 계약서, 언어 또는 적대적 입력 전반에 걸쳐 보편적인 정확성을 확립할 수 없습니다.
로컬 추론은 데이터 처리에 대한 더 큰 제어를 제공하지만, 자동으로 완전한 개인 정보 보호 보장은 아닙니다. 애플리케이션 구성 및 선택적 통합도 중요합니다.
## 6. SOLID 원칙 및 엔지니어링 결정
ScopeGhost는 여러 소프트웨어 엔지니어링 원칙을 적용하여 동작의 유지보수성과 테스트 용이성을 높였습니다.
### 단일 책임 원칙 (Single Responsibility Principle)
분석, 인용 검증, 주제 관련성 확인, 재무 계산, 영속화(persistence) 등은 각각 고유한 책임을 가집니다. 모델은 송장 총액을 계산할 필요가 없으며, 재무 엔진 역시 고객의 의도를 해석할 필요가 없습니다.
### 관심사 분리 (Separation of Concerns)
확률적 추론(Probabilistic reasoning)은 결정론적 비즈니스 규칙과 분리되어 있습니다. 이는 인용 검증이나 재무 산술을 지배하는 규칙을 의도적으로 변경하지 않고도 프롬프트를 개선하거나 추론 클라이언트(inference client)를 변경하기 쉽게 만듭니다.
### 안전하게 실패하고 불확실성을 보존 (Fail Safely and Preserve Uncertainty)
누락된 증거가 자동으로 범위 외(out-of-scope) 결론이 되어서는 안 됩니다. 서비스가 관련 계약적 제외 사항을 확립할 수 없을 경우, 부당한 자신감으로 뒷받침되지 않은 주장을 제시하는 대신 모호한 결과(ambiguous result)를 반환할 수 있습니다.
### 깊이 방어 (Defense in Depth)
애플리케이션은 하나의 프롬프트 지침에 의존하기보다 여러 계층을 사용합니다:
- 신뢰할 수 없는 증거 프레임(Untrusted evidence framing).
- 구조화된 출력 검증(Structured output validation).
- 조항 참조 검증(Clause-reference validation).
- 인용 검증(Citation verification).
- 주제 관련성 필터링(Topic-relevance filtering).
- 제외 자격 확인(Exclusion eligibility checks).
- 인간 검토(Human review).
이러한 통제 장치들은 서로 다른 실패 모드에 대응합니다. 어느 것도 모든 공격이나 잘못된 결론에 대한 보호를 보장하지는 않습니다.
### 결정론적 재무 논리 (Deterministic Financial Logic)
재무 계산은 생성된 부동 소수점(floating-point) 총액에 의존하기보다 정수 센트 산술(integer-cent arithmetic)을 사용합니다.
예를 들어, 시간당 $150의 예시 요율로 20시간 작업은 추정 인건비 $3,000을 나타냅니다. 개발자는 여전히 해당 추정치를 검토하고 최종 상업 제안을 승인할 책임이 있습니다.
### 테스트 용이성 및 재현성 (Testability and Reproducibility)
합성된 고정 데이터(Synthetic fixtures), 단위 테스트(unit tests), 회귀 방지 장치(regression harness), 그리고 선택적 로컬 추론 테스트는 시스템의 여러 부분을 독립적으로 검증하기 쉽게 만듭니다.
다음 다이어그램은 이러한 설계 관계를 요약합니다:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
flowchart TB
A["ScopeGhost Application"]
A --> B["Analysis Service"]
...
이는 코드베이스 전반에 걸쳐 모든 SOLID 원칙이 공식적으로 증명되었다고 주장하는 것이 아니라, 의도된 컴포넌트 경계를 보여줍니다.
## 7. 보안 및 프롬프트 주입 처리
클라이언트 통신은 신뢰할 수 없는 입력(untrusted input)입니다. 메시지에는 모델의 지침을 무효화하거나 계약상 예외를 조작하려는 텍스트가 포함될 수 있습니다.
ScopeGhost는 명시적인 신뢰할 수 없는 증거 프레이밍(untrusted-evidence framing)과 결정론적 검사(deterministic checks)를 사용하여 이러한 내용이 승인된 계약적 발견(contractual finding)이 되는 것을 방지하는 데 도움을 줍니다.
flowchart TD
A["Untrusted Client Message"] --> B["Evidence Encapsulation"]
B --> C["Local Model Inference"]
...
보고된 라이브 통합 테스트에서, 적대적 프롬프트(adversarial prompt)가 조작된 조항 ID를 도입하려고 시도했습니다. 프로덕션 검증 계층(production validation layer)은 그 알 수 없는 참조를 거부했습니다.
이는 특정 보호 장치가 테스트된 시나리오에서 작동함을 보여줍니다. Gemma 3가 프롬프트 주입에 면역이라는 것을 의미하거나 모든 가능한 적대적 요청이 포착될 것이라는 의미는 아닙니다.
## 8. 재무 계산 워크플로우
재무 엔진은 검토된 노력 추정치(reviewed effort estimates)를 재현 가능한 비용 범위로 변환합니다.
flowchart TD
A["Candidate Scope Change"] --> B["Review Estimated Hours"]
B --> C["Set Hourly Rate"]
...
기본 관계는 다음과 같습니다:
\[
\text{Estimated Cost}=\text{Estimated Hours}\times\text{Hourly Rate}
\]
시간당 $150 기준으로 20시간의 작업은 $3,000의 인건비 추정치를 산출합니다. 이 결과는 제공된 입력값으로부터 나온 계산일 뿐이며, 실제 구현 노력이나 최종 프로젝트 비용을 보장하지 않습니다.
## 9. SDLC: 문제 정의부터 릴리스 검토까지
저는 ScopeGhost를 일회성 AI 코드 생성 연습으로 다루기보다는 반복적인 소프트웨어 개발 수명 주기(Software Development Life Cycle, SDLC)를 통해 접근했습니다.
### 단계 1 — 요구사항
저는 고정된 범위의 프리랜서 계약에서 발생하는 '범위 확장(scope creep)'을 핵심 문제로 정의했습니다. 요구사항에는 증거 기반 분류, 누락된 증거에 대한 보수적 처리, 검토 가능한 변경 요청 워크플로우가 포함되었습니다.
### 단계 2 — 아키텍처 및 위협 모델링
저는 추론(inference)을 결정론적 유효성 검사 및 재무 계산과 분리했습니다. 또한 조작된 견적서, 알 수 없는 조항 ID, 관련 없는 제외 항목, 클라이언트가 제공한 텍스트 내의 적대적 지침이 관련된 실패 사례도 고려했습니다.
### 단계 3 — 점진적 구현
애플리케이션은 타입 지정 인터페이스(typed interfaces), 구조화된 스키마(structured schemas), 추론 클라이언트, 분석 서비스, 영속성(persistence), 그리고 사용자 대면 워크플로우를 사용하여 검토 가능한 증분으로 구축되었습니다.
### 단계 4 — 검증
테스트 전략에는 단위 테스트(unit tests), 합성 회귀 테스트(synthetic regression tests), 옵트인 라이브 추론 테스트(opt-in live inference tests), 브라우저 테스트, 타입 검사(type checking), 그리고 프로덕션 빌드가 포함됩니다.
### 단계 5 — 문서화 및 출시 검토
리포지토리에는 설정 지침, 평가 더미(evaluation fixtures), 테스트 프레임워크, 기술 문서를 포함합니다. M4.9 평가 프레임워크와 Hacktoberfest 제출 자료가 리포지토리에 커밋되었습니다.
### 단계 6 — 사용자 검증
다음 단계는 실제 프리랜서 및 소규모 에이전시로부터 피드백을 얻는 것입니다. 그들의 경험은 증거 제시 방식과 변경 요청 워크플로우가 지속 가능한 제품을 지원할 만큼 충분히 중요한 문제를 해결하는지 판단하는 데 도움이 될 것입니다.
이는 공식 인증이나 모든 가능한 릴리스 프로세스 완료를 주장하는 것이 아니라, 반복적인 SDLC(Software Development Life Cycle) 접근 방식입니다.
## 10. 테스트 아키텍처 및 평가 결과
ScopeGhost는 결정론적 안전장치, 모의 기반 회귀 평가, 그리고 라이브 모델 통합을 분리합니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
flowchart TB
A["ScopeGhost Verification"]
...}
합성 회귀 벤치마크
버전별 코퍼스 v2.0.0-synthetic에 대한 보고된 npm run test:eval 결과는 다음과 같습니다:
| 지표 | 결과 |
|---|
| 합성 평가 케이스 | 36 |
| ... | |
중요 제한 사항: 이 벤치마크는 DeterministicHarnessModel과 프로덕션 ScopeAnalysisService를 거친 사전 기록된 완료본을 사용합니다. 이는 회귀 동작 및 결정론적 안전장치를 평가하는 것이며, 36개의 독립적인 실시간 모델 응답에 대한 벤치마크가 아니거나 실제 계약 정확도의 증거가 아닙니다. | |
실시간 Ollama 통합 테스트
저장소에는 로컬 gemma3:4b 추론을 사용하는 네 가지 옵트인(opt-in) 테스트가 포함되어 있습니다:
- 실시간 조항 인용 추출 및 검증.
- 분석 오케스트레이션 및 SQLite 영속성.
- 증거가 불충분할 때의 불확실성 보존.
- 발명된 계약 조항 참조와 관련된 프롬프트 주입 시나리오.
이 테스트들은 범용적인 모델 견고성을 테스트하는 것이 아니라 특정 시나리오를 실행합니다.
검사 재현하기
# 단위 테스트 스위트
npm test
...
실시간 통합 스위트는 Ollama와 gemma3:4b 모델을 필요로 합니다. 정확한 옵트인 요구 사항은 저장소 README를 참조하십시오.
11. 로컬 배포 및 데이터 흐름
로컬 우선(local-first) 설계는 개발자가 핵심 추론 워크플로우를 자신의 기기에서 실행할 수 있도록 합니다.
flowchart TB
subgraph DEVICE["개발자 머신"]
A["브라우저"]
...