AI 튜토리얼

SoftJL Community 시작 가이드: AI로 요구사항, UML, 테스트 및 설명서 연결하기

이 글에서는 SoftJL Community를 배포하고 OpenAI 호환 모델을 구성하는 방법을 소개합니다. 또한 도서관 좌석 예약 시스템을 예로 들어 요구사항 확인, 타당성 분석, UML 모델링, 테스트 커버리지 및 엔지니어링 설명서 생성을 완료합니다.

2026년 10월 15일약 15분 소요

SoftJL Community 시작 가이드: AI로 요구사항, UML, 테스트 및 설명서 연결

SoftJL Community란

SoftJL Community는 소프트웨어 관련 졸업 설계, 과제 설계 및 UML 과제를 위한 독립 배포형 AI 소프트웨어 공학 워크벤치입니다. 요구사항 분석, 타당성 분석, UML 모델링, 설계, 테스트, 공학 문서 및 변경 추적을 연결하여 요구사항이 설계와 테스트에 반영되었는지 확인하고, 수정, 발표 및 답변 준비에 필요한 추적 가능한 근거를 정리할 수 있도록 지원합니다.

커뮤니티 버전은 전체 소스 코드를 제공하며 Apache License 2.0에 따라 배포됩니다. 공식 웹사이트 호스팅 버전과 비교하면 커뮤니티 버전은 서비스, 데이터베이스 및 모델 공급자를 직접 관리해야 하지만, 요구사항 규칙 추출, 전체 요구사항 및 설계 모델, 테스트 커버리지, 설명서 생성, 출처 추적, 프로젝트 관리 및 BYOK 모델 연결 등 주요 기능은 그대로 제공합니다.

핵심 작업 흐름

플랫폼은 요구사항부터 검증까지 이어지는 하나의 공학적 흐름을 중심으로 작동합니다. 먼저 요구사항을 입력하고 규칙을 확인한 다음 타당성 분석을 수행하고, 요구사항 모델과 설계 모델을 생성합니다. 이어서 테스트 케이스와 커버리지 매트릭스를 생성하고, 마지막으로 편집 및 다운로드할 수 있는 공학 설명서를 생성합니다.

요구사항 규칙: 자연어 요구사항에서 규칙을 추출하고 품질 검사, 수정, 수동 확인 및 인수 조건 정리를 수행합니다.
타당성 분석: 시스템 환경도, 업무 및 시스템 흐름도, 구현 방안 분석을 생성합니다.
UML 모델: 기능 구조, 유스케이스, 도메인 개념, 프로토타입 화면, 배포 요구사항, 전체 아키텍처, 설계 클래스 및 데이터베이스 등의 모델을 구축합니다.
테스트 및 커버리지: 정상, 오류 및 경계 시나리오의 테스트 케이스를 생성하고 커버리지 매트릭스와 추적 매트릭스로 누락된 부분을 파악합니다.
공학 문서: 타당성 조사 보고서, 요구사항 명세서 및 소프트웨어 설계 설명서를 생성하며 버전 관리와 DOCX 다운로드를 지원합니다.
변경 영향: 요구사항, 설계, 테스트 및 설명서 간의 출처 관계를 확인하여 수정 후 어떤 산출물을 갱신해야 하는지 판단합니다.
모델 연결: OpenAI 호환 모델 서비스를 구성하여 자체 모델 공급자를 호출합니다.

생성 결과는 공학적 근거를 찾고 정리하는 데 사용되며, 모델 제약 조건, 다이어그램 내용, 설명서의 업무 일관성을 수동으로 확인하고 실제 시스템에서 테스트를 실행해야 합니다.

설치 전 환경 준비

처음 실행하려면 다음 환경을 준비해야 합니다.

Node.js 22
npm 10
Java 21
Graphviz
선택 사항: PostgreSQL과 OnlyOffice 실행을 위한 Docker

렌더링 서비스를 처음 사용할 때 시스템에서 PDF 중국어 글꼴을 다운로드하기 위해 인터넷 연결이 필요할 수 있습니다. Docker는 핵심 서비스를 임시로 체험하는 데 필수는 아니지만, 장기간 사용하려면 영구 PostgreSQL을 구성하는 것이 좋습니다. DOCX를 온라인으로 편집하려면 OnlyOffice도 활성화해야 합니다.

핵심 서비스 빠르게 시작하기

1. 소스 코드 가져오기 및 종속성 설치

git clone https://github.com/guolola/SoftJL.git
cd SoftJL
npm ci

2. 개발 환경 시작

npm run dev

이 명령은 contracts 및 prompts 공유 패키지를 자동으로 빌드하고 Web, API 및 렌더링 서비스를 병렬로 시작합니다. Web은 일반적으로 http://localhost:3000에서 실행되고, API는 4101 포트, Render Service는 4002 포트를 사용합니다.

Web 출력에 Ready가 표시되면 http://localhost:3000을 열 수 있습니다. 동시에 다음 상태 확인도 권장합니다.

http://localhost:3000/api/health
http://127.0.0.1:4002/health

두 상태 확인 인터페이스 모두 status: "ok"가 포함된 결과를 반환해야 합니다.

3. 임시 메모리 모드 이해하기

npm run dev를 직접 실행하면 기본적으로 임시 메모리 모드가 사용됩니다. 서비스를 다시 시작하면 계정, 프로젝트, 모델 서비스 구성 및 실행 기록이 사라집니다. 문서 파일은 별도로 로컬 디렉터리에 저장되지만 데이터베이스 백업을 대신할 수 없습니다. 따라서 이 모드는 빠른 체험에 적합하며 프로젝트를 장기간 보관하는 데는 적합하지 않습니다.

영구 데이터베이스 및 온라인 편집 구성

개발용 PostgreSQL 사용

공식 웹사이트 홈 — 데스크톱 첫 화면

로컬 컴퓨터에 Docker를 설치하고 시작한 후 다음 명령으로 전용 개발 데이터베이스와 핵심 서비스를 실행할 수 있습니다.

npm run dev:postgres

이 방식은 데이터베이스를 Docker 데이터 볼륨에 저장합니다. 스크립트의 데이터베이스 인증 정보는 로컬 개발에만 사용되므로 운영 환경에서는 반드시 교체해야 하며, 기존 전체 버전 데이터베이스를 커뮤니티 버전 데이터베이스로 직접 사용해서는 안 됩니다.

기존 PostgreSQL 연결

PostgreSQL을 이미 준비했다면 루트 디렉터리의 .env.example을 .env로 복사한 다음 DATABASE_URL과 직접 생성한 UML_PROVIDER_CONFIG_SECRET을 설정합니다.

cp .env.example .env

구성을 완료한 후 npm run dev를 다시 실행합니다. 암호화 키를 안전하게 보관해야 합니다. UML_PROVIDER_CONFIG_SECRET을 임의로 변경하면 저장된 모델 공급자 인증 정보를 복호화할 수 없게 됩니다. 데이터베이스 연결 정보와 키도 Git에 커밋해서는 안 됩니다.

OnlyOffice 활성화

설명서를 온라인으로 편집하려면 먼저 Docker 엔진을 시작한 후 다음을 실행합니다.

npm run dev:full

이 스크립트는 로컬 컴퓨터의 8080 포트에서 OnlyOffice를 확인합니다. 서비스를 사용할 수 없으면 해당 컨테이너를 생성하거나 시작하며, 처음 실행할 때는 이미지를 다운로드해야 할 수 있습니다. 핵심 서비스만으로도 문서를 생성하고 다운로드할 수 있지만, 온라인 편집 기능에는 OnlyOffice를 추가로 구성해야 합니다.

AI 모델 서비스 구성

Web 서비스를 시작하고 계정에 로그인합니다.
계정 설정으로 이동하여 OpenAI 호환 Provider를 추가합니다.
모델 공급자의 HTTPS Base URL과 API Key를 입력합니다.
모델 검색 및 연결 테스트를 실행합니다.
사용 가능한 모델 하나를 기본 모델로 선택합니다.

자체 배포 환경에서는 자체 모델 서비스를 사용하며 모델 호출 비용은 해당 공급자가 청구합니다. 운영 환경에서는 영구 데이터베이스와 인증 정보 암호화 키를 사용하고, 개발용 게스트 및 legacy 평문 대체 진입점을 비활성화해야 합니다.

도서관 좌석 예약 시스템으로 모델링 한 번 수행하기

다음은 간단한 요구사항의 예입니다. 학생이 로그인한 후 빈 좌석을 조회하고 날짜와 시간대를 선택하여 예약을 제출합니다. 같은 학생은 같은 시간대에 중복 예약을 할 수 없으며, 예약이 성공하면 알림을 보냅니다. 관리자는 좌석을 관리하고 예약 기록을 확인하며 예외 취소를 처리할 수 있습니다.

1단계: 프로젝트 생성 및 요구사항 규칙 확인

프로젝트를 생성한 후 위의 업무 설명을 플랫폼에 입력하여 시스템이 요구사항 규칙을 추출하도록 합니다. 사용자 역할, 예약 조건, 중복 예약 제약, 알림 동작 및 예외 취소 흐름을 중점적으로 확인합니다. 문제가 없으면 규칙과 인수 조건을 저장하여 이후 모델이 모호한 요구사항을 기반으로 구축되지 않도록 합니다.

2단계: 타당성 분석 완료

프로젝트 흐름에 따라 다음 세 가지 분석을 완료합니다.

시스템 환경도: 학생, 관리자, 알림 서비스 및 예약 시스템 사이의 경계와 상호작용을 명확히 합니다.
업무 및 시스템 흐름도: 좌석 조회, 예약 제출, 알림 전송 및 예외 취소의 처리 흐름을 정리합니다.
구현 방안: 후보 방안을 비교하고 비용, 이익 및 위험을 기록합니다.

분석을 완료한 후 먼저 시스템 경계와 흐름이 원래 요구사항에 부합하는지 확인한 다음 모델 생성 단계로 넘어갑니다.

3단계: 요구사항 모델 및 설계 모델 생성

플랫폼은 확인이 완료된 요구사항을 바탕으로 기능 구조, 전체 업무 흐름, 유스케이스, 도메인 개념, 프로토타입 화면 관계 및 배포 요구사항을 포함한 전체 요구사항 모델을 생성할 수 있습니다. 요구사항 모델을 확인한 후 선행 관계에 따라 전체 아키텍처, 유스케이스 실현, 설계 클래스, 페이지 탐색, 데이터베이스, 컴포넌트 관계 및 배포 설계와 같은 설계 모델을 생성합니다.

대시보드 통계 및 산출물 생성 시간

생성 후 출처 관계를 열어 각 설계 요소가 요구사항 규칙까지 추적 가능한지 확인합니다. 이렇게 하면 예약 규칙이 변경되었을 때 영향을 받는 유스케이스, 클래스, 데이터베이스 설계 및 테스트를 쉽게 식별할 수 있습니다.

4단계: 테스트 및 커버리지 매트릭스 생성

예약 시스템에 대해 최소한 다음 시나리오를 확인합니다.

학생이 지정한 날짜와 시간대의 빈 좌석을 조회할 수 있어야 합니다.
학생이 유효한 예약을 제출하고 알림을 받을 수 있어야 합니다.
같은 학생이 같은 시간대에 중복 예약을 시도하면 시스템이 요청을 거부해야 합니다.
빈 좌석이 없거나 시간대가 유효하지 않거나 예약 정보가 누락된 경우 시스템이 예외를 처리해야 합니다.
관리자가 좌석을 관리하고 예약 기록을 확인하며 예외 취소를 처리할 수 있어야 합니다.

커버리지 매트릭스와 추적 매트릭스를 통해 설계 근거 또는 테스트 근거가 없는 요구사항을 찾습니다. 플랫폼이 생성한 테스트 케이스는 실제 시스템에서 실행해야 하며, 생성 성공만으로 인수 결과를 대신할 수 없습니다.

5단계: 공학 설명서 생성

타당성 분석, 요구사항 모델 및 설계 모델을 완료한 후 세 가지 유형의 공학 문서를 생성할 수 있습니다. 타당성 조사 보고서, 요구사항 명세서 및 소프트웨어 설계 설명서입니다. 생성 후 본문과 다이어그램이 일치하는지 확인하고 학교 템플릿과 형식 요구사항에 맞게 수정한 다음 버전 관리 및 DOCX 다운로드를 진행합니다.

요구사항 변경 처리 방법

예를 들어 프로젝트 규칙을 “같은 학생은 같은 시간대에 중복 예약할 수 없다”에서 “같은 학생은 하루에 최대 두 개의 시간대를 예약할 수 있다”로 변경한다고 가정합니다. 설명서의 한 문장만 수정하지 말고 출처와 의존 관계를 따라 다음을 확인해야 합니다.

새 요구사항 규칙을 저장하고 확인합니다.
출처 관계와 변경 영향을 열어 영향을 받는 요구사항, 유스케이스, 설계 및 테스트 산출물을 확인합니다.
의존 순서에 따라 요구사항 모델과 설계 모델을 업데이트합니다.
데이터베이스 제약, 업무 흐름 및 예외 처리를 다시 확인합니다.
테스트 케이스와 커버리지 매트릭스를 업데이트하고 실제 시스템에서 회귀 테스트를 실행합니다.
관련 설명서를 다시 생성하거나 수정하고 버전 기록을 보존합니다.

출처 연결선과 커버리지 수치는 점검 범위를 찾는 데 도움이 되지만, 최종적으로는 구체적인 모델을 열어 제약 조건, 입력 조건 및 동작이 완전한지 확인해야 합니다.

외부 Coding Agent 연결

커뮤니티 버전에서는 배포자가 읽기 전용 MCP 연결을 직접 활성화하여 호환되는 Coding Agent가 프로젝트 범위 내에 저장된 설계, 인수 조건, 공학 제약 및 테스트 정보를 읽도록 할 수 있습니다. MCP 로컬 체험 진입점은 사이드바의 “프로그래밍 도우미” 또는 프로젝트 설정의 “이 프로젝트 연결”이며, 사용하기 전에 설치와 빌드를 완료해야 합니다.

npm run dev:mcp

이 연결은 공학적 근거를 읽기 전용으로 제공할 뿐 코드 검토, 실제 실행 및 테스트 인수를 대신하지 않습니다. README에도 실제 Coding Agent 클라이언트 호환성과 생성 코드 인수가 아직 개선 중이라고 명시되어 있으므로 사용할 때는 MCP 연결 안내를 참고해야 합니다.

자주 사용하는 개발 명령

npm run build:packages: contracts 및 prompts 공유 패키지를 빌드합니다.
npm run build: 공유 패키지와 모든 애플리케이션을 빌드합니다.
npm run dev:render: PlantUML 렌더링 서비스를 단독으로 시작합니다.
npm run test:contracts: 공유 계약을 검증합니다.
npm run test:api: API 테스트를 실행합니다.
npm run test:render: 렌더링 서비스 테스트를 실행합니다.
npm run test:web: 전체 Web 테스트를 실행합니다.
npm run typecheck:web: Web 타입을 검사합니다.
npm run lint:web: Web 정적 검사를 실행합니다.
npm audit --audit-level=high: 종속성 보안 공지를 확인합니다.

공유 패키지가 변경된 후 애플리케이션을 단독으로 시작하거나 테스트를 실행하기 전에 먼저 npm run build:packages를 실행해야 합니다. 빌드 출력, 환경 구성, 개인 키, 로그 및 로컬 실행 데이터는 Git 무시 범위에 유지해야 합니다.

아키텍처 개요

프로젝트는 여러 애플리케이션과 공유 패키지로 구성된 구조를 사용합니다.

apps/web: React, Next.js 워크스페이스 및 페이지.
apps/api: Fastify API, 인증, 생성 파이프라인, 실행 기록 및 문서 조립.
apps/render-service: PlantUML 다이어그램 렌더링.
packages/contracts 및 packages/prompts: 공유 계약 및 생성 프롬프트.
packages/harness-e2e 및 packages/harness-eval: 인수 테스트 및 품질 평가.

배포 및 사용 시 주의사항

커뮤니티 버전은 독립된 데이터베이스를 사용해야 하며, 공식 웹사이트 정식 버전 데이터베이스의 축소 대체용으로 사용해서는 안 됩니다.
개발 시작 스크립트의 데이터베이스 인증 정보는 로컬 사용에만 적합하므로, 프로덕션 환경에서는 반드시 변경해야 합니다.
모델 키, 데이터베이스 연결 정보 및 암호화 키를 코드 저장소에 커밋해서는 안 됩니다.
프로젝트 설명서는 프로젝트 보고서 자료로 사용할 수 있지만, 완성된 졸업 논문을 대신하지는 않습니다.
다이어그램, 설명서 및 코드의 업무 일관성은 수동으로 점검하고 실행 증거를 통해 검증해야 합니다.
프로덕션 배포 전에 서비스 도메인, 데이터베이스, 이메일 및 모델 설정을 교체해야 합니다.

요약

SoftJL Community는 졸업 작품이나 수업 프로젝트를 엔지니어링 프로세스에 따라 구성하려는 개발자에게 적합합니다. 환경 설치, 데이터베이스 및 모델 설정을 완료하면 요구사항 규칙을 바탕으로 타당성 분석, UML 요구사항 및 설계 모델, 테스트 커버리지와 프로젝트 설명서를 단계적으로 생성하고, 요구사항 변경 시 영향 범위를 추적할 수 있습니다.

자료가 분산되고 반복적으로 정리되는 문제를 줄일 수 있지만, 수동 설계 판단, 코드 구현, 실제 테스트 및 최종 발표 준비를 대신할 수는 없습니다. 플랫폼에서 생성된 콘텐츠를 추적 가능한 엔지니어링 초안과 점검 근거로 활용하고, 학교의 요구사항 및 실제 시스템 실행 결과를 반영하여 최종 결과물을 완성하는 것이 좋습니다.