ontology-driven-dev로 비즈니스 요구사항에서 온톨로지 기반 관리 시스템 구축

프로젝트 소개

ontology-driven-dev는 비즈니스 시스템 개발을 위한 AI 스킬로, “요구사항 탐색 → 온톨로지 모델링 → 애플리케이션 구축”의 강한 순서를 따르는 3단계 방법론을 사용합니다. 한 줄의 비즈니스 설명에서 시작해 각 단계마다 사람이 확인하면 요구사항 명세서, 7개 모델 YAML, 실행 가능한 브라우저 기반 프런트엔드와 백엔드 시스템을 얻을 수 있습니다.

핵심 목표는 AI가 단순히 코드를 빠르게 생성하도록 하는 것이 아니라, 요구사항 문서, 온톨로지 모델, 최종 코드가 엄격하게 일치하도록 보장하는 것입니다. 데이터베이스 테이블, 인터페이스, 메뉴, 권한, 프로세스, 규칙 및 보고서는 모두 모델을 의미의 원천으로 삼아 요구사항, 설계 및 구현이 서로 분리되는 문제를 줄입니다.

요구사항 탐색 단계에는 8개의 절차가 포함되며, 각 절차마다 반드시 일시 중지하고 사람의 확인을 기다려야 합니다. Agent가 자동으로 건너뛸 수 없습니다.

핵심 기능 및 프로젝트 구조

주요 특징

• 요구사항 추적성: 모든 기능을 요구사항 명세서의 해당 항목까지 추적할 수 있습니다.
• 7개 모델의 통합 의미 체계: M1, M2, M3, M5, M6, M7 및 MU YAML을 사용해 객체, 동작, 규칙, 주체, 프로세스, 조회·보고서 및 UI를 설명합니다.
• 사람 확인 게이트: 요구사항 탐색의 단계 0부터 단계 7까지 모두 사람의 확인을 거쳐야 다음 단계로 진행할 수 있습니다.
• 내장 기술 기반: code-paas는 Flask, SQLite, React 및 TypeScript 기반의 모놀리식 애플리케이션을 제공하며, 시스템 관리, 프로세스 엔진, 워크벤치 및 온톨로지 레지스트리를 포함합니다.
• AI 네이티브 상호작용: 생성된 애플리케이션에는 오른쪽 AI 대화 상자가 반드시 포함되어야 하며, 온톨로지 레지스트리 주입, 도구 호출, SSE 스트리밍 응답 및 읽기 전용 SQL 보안 경계를 지원합니다.
• 다중 도구 호환: WorkBuddy, Claude Code, Codex, Cursor, Aider, Cline 및 프로젝트 지침을 로드할 수 있는 범용 Agent에서 사용할 수 있습니다.

저장소의 주요 내용

• SKILL.md: 방법론, 3단계 파이프라인 및 반드시 준수해야 하는 실행 원칙을 정의합니다.
• references/: 요구사항 작성 규칙, 온톨로지 모델링 프레임워크, 모델에서 구현으로 이어지는 개발 지침, AI 네이티브 기술 아키텍처 및 UI/UE 규칙을 포함합니다.
• reference-example/: 판매 계약 실행 관리의 전체 예제로, 요구사항 문서, 7개 모델 YAML 및 manifest.json을 포함합니다.
• techbase/: 복사하고 확장할 수 있는 code-paas 소스로, 백엔드, 프런트엔드, 모델 예제 및 종속성 파일을 포함합니다.

실행 환경 준비

시작하기 전에 로컬 환경에 다음 항목이 갖춰져 있는지 확인하세요.

• Python 3.10 이상.
• Node.js 18 이상.
• Python 및 프런트엔드 종속성을 처음 설치할 때 네트워크에 연결할 수 있어야 합니다.

백엔드는 Flask와 SQLite를 사용하고, 프런트엔드는 React, TypeScript 및 Vite를 사용합니다. 프로젝트는 MIT License를 적용하므로 자유롭게 사용, 수정 및 재배포할 수 있습니다.

AI 개발 도구에 설치

Claude Code에 설치

Claude Code는 스킬 디렉터리의 SKILL.md를 자동으로 검색할 수 있습니다. 모든 프로젝트에서 사용할 수 있도록 사용자 수준에 설치할 수 있습니다.

cp -r ontology-driven-dev ~/.claude/skills/ontology-driven-dev

현재 프로젝트에 설치할 수도 있습니다.

cp -r ontology-driven-dev .claude/skills/ontology-driven-dev

설치가 완료되면 Claude Code는 스킬 frontmatter의 name과 description에 따라 프로세스를 식별하고 로드합니다.

WorkBuddy에 설치

사용자 수준 설치 명령은 다음과 같습니다.

cp -r ontology-driven-dev ~/.workbuddy/skills/ontology-driven-dev

하나의 프로젝트에서만 사용하려면 다음을 실행합니다.

cp -r ontology-driven-dev <你的项目>/.workbuddy/skills/ontology-driven-dev

Codex에 설치

Codex에는 기본 제공 스킬 레지스트리가 없으므로 먼저 스킬을 저장소에 복사해야 합니다.

mkdir -p .codex/skills
cp -r ontology-driven-dev .codex/skills/

그런 다음 프로젝트의 codex.md 또는 AGENTS.md에 로드 규칙을 추가합니다.

사용자가 “온톨로지 기반 개발, 요구사항 탐색, 온톨로지 모델링, 7개 모델, code-paas 또는 AI 네이티브 애플리케이션”을 요청하면 .codex/skills/ontology-driven-dev/SKILL.md를 로드하고, 3단계 프로세스 및 사람 확인 게이트를 엄격히 준수하여 실행합니다.

Codex는 사람 확인을 대화형 질문 또는 승인 절차로 매핑합니다. npm install 및 pip install을 실행하려면 Codex가 실행되는 샌드박스에서 네트워크에 연결할 수 있어야 합니다.

Cursor, Aider 또는 Cline에서 사용

• Cursor: SKILL.md의 내용을 프로젝트 규칙 또는 .cursorrules에 추가합니다.
• Cline, Aider: 세션 시작 시 SKILL.md를 붙여넣거나 Agent에 해당 경로를 로드하도록 명시적으로 요청합니다.
• 기타 Agent: 해당 파일을 시스템 지침 또는 프로젝트 메모리로 컨텍스트에 주입합니다.

1단계: 요구사항 탐색 및 확인

1단계는 references/AI需求探索与确认提示词V9.0.md를 기반으로 초기 비즈니스 설명을 정식 소프트웨어 요구사항 명세서로 정리합니다.

Agent에 다음과 같은 지시를 입력할 수 있습니다.

판매 계약 실행 관리 시스템을 개발해 주세요. 계약, 대금 회수, 납품 및 승인을 관리해야 합니다.

Agent는 다음 8개 단계를 순서대로 진행해야 합니다.

1. 전체적인 이해.
2. 비즈니스 객체.
3. 비즈니스 기능 및 규칙.
4. 객체 간 연동.
5. 엔드투엔드 협업 및 승인 흐름.
6. 조회, 통계 및 보고서.
7. 역할 및 권한.
8. UI 프로토타입. 필요에 따라 선택할 수 있습니다.

각 단계가 끝나면 Agent는 반드시 “질문, AI 제안, 이유, 기타 선택지, 빠른 답변” 형식으로 확인을 요청하고, 사용자의 결정을 기다리며 일시 중지해야 합니다. 기업별 B 유형 내용도 반드시 명확하게 질문해야 하며, 확인되지 않은 상태에서는 다음 단계로 진행할 수 없습니다.

이 단계에서 최종적으로 다음 파일이 생성됩니다.

<业务域>-요구사항 명세서-V9.md

문서의 부록 C는 다음 단계의 7개 모델링을 위한 입력 기준이므로, 비즈니스 객체, 프로세스, 규칙, 역할 및 보고서가 완전한지 중점적으로 확인해야 합니다.

2단계: 7개 모델 YAML 생성

요구사항 확인이 완료되면 Agent는 references/ontology_modeling_framework_v9.md 및 요구사항 문서의 부록 C를 바탕으로 온톨로지 모델을 구축합니다. 이 시점의 입력은 이미 확정된 기준이므로 대규모 비즈니스 분해를 다시 수행해서는 안 됩니다.

요구사항 명세서가 이미 준비되어 있다면 모델링만 수행하는 프로세스를 직접 실행할 수 있습니다.

이 요구사항 명세서를 기반으로 온톨로지 모델링을 수행하고, 7개 모델 YAML과 manifest.json을 출력해 주세요.

yaml/ 디렉터리에 출력되는 내용은 다음과 같습니다.

• M1 객체 모델: 비즈니스 객체를 설명합니다.
• M2 동작 모델: 비즈니스 동작을 설명합니다.
• M3 규칙 모델: 비즈니스 규칙을 설명합니다.
• M5 주체 모델: 역할 및 관련 주체를 설명합니다.
• M6 프로세스 모델: 비즈니스 프로세스를 설명합니다.
• M7 조회·보고서 모델: 조회 및 보고서를 설명합니다.
• MU UI 모델: 사용자 인터페이스를 설명합니다.
• manifest.json: 모델 목록을 기록합니다.

모델링이 완료되면 일관성 검사를 수행해야 하며, 최소한 요구사항 추적성, M7과 M2의 일대일 관계, M6 참조의 순환 여부를 검사해야 합니다. 불일치가 발견되면 먼저 모델을 수정한 후 코드 구축 단계로 진행해야 합니다.

3단계: 실행 가능한 BS 시스템 구축

code-paas 기술 기반 복사

스킬 디렉터리의 techbase/ 전체를 현재 프로젝트의 code-app/으로 복사합니다.

cp -r <技能根目录>/techbase/. <当前项目>/code-app/
cd <当前项目>/code-app/frontend && npm install
cd <当前项目>/code-app/backend && pip install -r requirements.txt

정식 개발 시에는 2단계에서 생성한 모델로 기반에 포함된 예시 7개 모델 YAML을 교체해야 합니다.

10단계 순서에 따른 구현

1. 7개 모델 YAML을 작성하거나 정리합니다.
2. DDL 및 데이터베이스 테이블을 생성합니다.
3. 데이터 사전을 등록합니다.
4. 동작 및 규칙 서비스를 구현합니다.
5. 역할 권한 시드 데이터를 작성합니다.
6. 프로세스 엔진을 연동합니다.
7. 메뉴, 페이지 및 라우트를 생성합니다.
8. 오른쪽 AI 대화 상자를 구현합니다.
9. 프런트엔드와 백엔드의 전체 경로를 통합 테스트합니다.
10. 요구사항과 모델을 기준으로 검수합니다.

오른쪽 AI 대화 상자는 필수 구성 요소이므로 개발 과정에서 생략해서는 안 됩니다. 프로젝트에서 정의한 온톨로지 레지스트리 주입, 도구 호출, SSE 스트리밍 전송 및 읽기 전용 SQL 보안 경계를 준수해야 합니다.

백엔드와 프런트엔드 시작

Flask 백엔드를 시작합니다.

cd code-app/backend
pip install -r requirements.txt
python app.py

백엔드 기본 접속 주소는 http://localhost:5000입니다.

별도의 터미널을 열어 프런트엔드 개발 서버를 시작합니다.

cd code-app/frontend
npm install
npm run dev

프런트엔드 기본 접속 주소는 http://localhost:5173입니다. 기본 계정은 admin, 기본 비밀번호는 admin123입니다. 기반 실행에 관한 자세한 내용은 techbase/README.md에서 확인할 수 있습니다.

일반적인 실행 방식

기존 입력과 목표에 따라 서로 다른 실행 문구를 사용할 수 있습니다.

요구사항부터 전체 개발 시작

장비 유지보수 관리 시스템을 개발해 주세요. 온톨로지 기반 개발 프로세스를 엄격히 따르고, 각 요구사항 탐색 단계마다 반드시 제 확인을 기다려 주세요.

온톨로지 모델링만 수행

이 요구사항 명세서를 기반으로 온톨로지 모델링을 수행하고 M1, M2, M3, M5, M6, M7, MU 및 manifest.json을 출력해 주세요.

기존 모델을 기반으로 애플리케이션 구축

이 7개 모델 YAML을 기반으로 시스템을 생성하고, code-paas 기반을 사용해 프런트엔드와 백엔드 통합 테스트를 완료해 주세요.

“온톨로지 기반”, “요구사항 탐색”, “온톨로지 모델링”, “7개 모델”, “code-paas”, “AI 네이티브 애플리케이션” 및 “비즈니스 시스템 개발”과 같은 키워드도 Agent가 스킬을 식별하는 데 도움이 됩니다.

고급 실무 권장 사항

사람 확인 게이트를 건너뛰지 마세요

초기 요구사항이 완전해 보이더라도 Agent에게 한 번에 시스템을 직접 생성하도록 요청하지 마세요. 단계별 확인을 통해 객체 경계, 승인 노드, 권한 범위 및 통계 기준과 같은 문제를 조기에 발견할 수 있습니다.

부록 C를 모델링 범위로 사용하세요

2단계는 요구사항 문서의 부록 C를 확정된 입력으로 삼아야 합니다. 모델링 중 핵심 비즈니스 내용이 누락된 것을 발견하면 모델이 확인되지 않은 비즈니스 범위를 임의로 확장하도록 하지 말고, 요구사항 단계로 돌아가 내용을 보완하고 확인해야 합니다.

모델 간 참조를 우선적으로 확인하세요

코드 구축에 들어가기 전에 M7과 M2의 대응 관계, M6의 참조 관계, 그리고 요구사항 항목에서 모델 요소까지의 추적 가능성을 중점적으로 확인해야 합니다. 모델 수준의 오류가 데이터베이스, 인터페이스, 페이지에 유입되면 이후 통합 연동 비용이 증가합니다.

대조용 골든 샘플 유지

reference-example/에는 판매 계약 실행 관리의 완전한 실제 예제가 제공됩니다. 처음 사용할 때는 그 안의 요구사항 명세서, 7개 모델 YAML, manifest.json을 대조해 각 단계 산출물 간의 연결 방식을 이해할 수 있습니다.

먼저 모델을 교체한 다음 기반을 확장

techbase/models/에 있는 것은 예시 모델입니다. 실제 프로젝트에서는 먼저 자체 7개 모델 YAML을 넣은 다음, 모델에서 구현으로 이어지는 10단계 파이프라인에 따라 백엔드 서비스, 권한, 프로세스, 메뉴 및 페이지를 확장해야 합니다. 예시 데이터를 중심으로 비즈니스 코드를 직접 수정하는 일은 피해야 합니다.

맺음말

ontology-driven-dev는 요구사항 명확화, 온톨로지 모델링, 애플리케이션 구현을 사람의 게이트 검토가 포함된 하나의 개발 흐름으로 연결합니다. 이를 올바르게 사용하는 핵심은 먼저 요구사항을 확정하고, 다음으로 7개 모델의 일관성을 검증한 뒤, 마지막으로 code-paas를 기반으로 구축하고 검수하는 것입니다. 이를 통해 AI를 활용해 업무 시스템 개발 효율을 높이는 동시에, 명확한 의미의 출처와 완전한 요구사항 추적 관계를 유지할 수 있습니다.