@soddong/agentic-domain-methodology

@soddong/agentic-domain-methodology는 Agentic Platform의 방법론 도메인 패키지입니다.

이 패키지는 Methodology, Lifecycle, Phase, Process, Stage, Activity, Task, Step, Gate, Handoff, Artifact Requirement, Common Blueprint Policy 같은 방법론 구조를 관리하기 위한 하위 도메인 패키지입니다.

현재 범위

현재는 패키지 skeleton, Continuous Publish/Delivery 기반, methodology SQLite schema migration, database helper, 핵심 Repository/Service API, Common Blueprint Policy, Activity Artifact Requirement의 artifact component 참조, Stage Criteria API, Handoff Requirement API, Managed ID Rule, Build Planning fixture/seed, runtime seed apply handler, 최소 validator, scoped validation을 제공합니다. Agent contribution은 후속 iteration에서 구체화합니다.

| 구분 | 상태 | | --- | --- | | 패키지 skeleton | 포함 | | 기본 문서 | 포함 | | build/typecheck | 포함 | | pack dry-run | 포함 | | 최소 public API | 포함 | | Methodology DB migration | 포함 | | Methodology database helper | 포함 | | Repository/Service | 핵심 생성/조회 API 포함 | | Common Blueprint Policy | 공통 Front/Back Matter 정책 포함 | | Activity Artifact Component Reference | Activity 산출물 요구가 artifact-standard의 특정 document component를 참조 가능 | | Task/Step Execution Model | Activity 하위 업무/논리 Task와 세부 실행 Step 구조 포함 | | Stage Criteria API | Stage entry/exit/gate 기준 생성/조회 가능 | | Handoff Requirement API | 수행 단위 간 전달 계약 생성/조회 가능 | | Managed ID Rule | 방법론 요소별 관리 ID formatter rule과 저장값 검증 포함 | | Runtime Seed Apply Handler | AI-Agent SDLC seed의 methodology section 적용 가능 | | Validator | 최소 구조 정합성 검증 포함 | | Fixture/Seed | Build Planning 예시 포함 | | Agent contribution | 후속 iteration | | CLI | 1차 구현 제외 | | Adapter | 1차 구현 제외 |

도메인 책임

@soddong/agentic-domain-methodology
  - Methodology
  - Lifecycle
  - Phase
  - Process
  - Stage
  - Activity
  - Task
  - Step
  - Gate
  - Entry/Exit Criteria
  - Handoff
  - Baseline
  - Artifact Requirement
  - Managed Identity Rule
  - Common Blueprint Policy
  - Trace Policy

표준 계층과 용어

방법론 구조의 표준 계층과 한글 표기는 다음을 기준으로 합니다.

Lifecycle 생애주기
  -> Phase 페이즈
    -> Process 프로세스
      -> Stage 단계
        -> Activity 활동
          -> Task 작업
            -> Step 절차

| 영문 | 한글 | 정의 | | --- | --- | --- | | Lifecycle | 생애주기 | 대상의 기획, 구축, 전환, 운영, 개선을 포괄하는 최상위 흐름 | | Phase | 페이즈 | 생애주기 안에서 목적과 전환점 기준으로 구분되는 큰 구간 | | Process | 프로세스 | 특정 Phase를 수행하기 위한 재사용 가능한 절차적 흐름 | | Stage | 단계 | Process 안에서 목적, 산출물 흐름, gate/handoff 기준으로 구분되는 수행 구간 | | Activity | 활동 | 특정 산출물 또는 의미 있는 결과를 만드는 수행 단위 | | Task | 작업 | Activity를 완수하기 위한 업무/논리 중심 작업 묶음 | | Step | 절차 | Task를 실제 수행하기 위한 세부 실행 절차 |

예를 들어 Build Planning Phase에는 Build Planning Process를 배치할 수 있고, 해당 process 내부에 분석 단계, 상위 설계 단계 같은 Stage가 위치합니다.

Activity Artifact Requirement와 Document Component 참조

methodology는 산출물 표준 내부 구조를 직접 소유하지 않습니다. 본문, 부록, 하위 부록 같은 산출물 구성 단위는 @soddong/agentic-domain-artifact-standard의 DocumentComponent가 정의합니다.

다만 Activity가 산출물 전체가 아니라 특정 구성 단위를 작성, 검토, 정제, 종합하는 경우가 있으므로 Activity Artifact Requirement는 optional component 참조를 가질 수 있습니다.

service.addActivityArtifactRequirement({
  activityId: activity.activityId,
  artifactStandardCode: "business_process_definition",
  artifactStandardVersion: "1.0.0",
  artifactComponentCode: "appendix_l3_process",
  artifactComponentRoleCode: "APPENDIX",
  requirementRoleCode: "output",
  outputUsageCode: "produces",
  isPrimary: true
});

의미는 다음과 같습니다.

Activity: L3 프로세스 부록 작성
  output artifact standard: [email protected]
  output component: appendix_l3_process
  usage: produces

이 구조에서 methodology는 "언제, 어떤 Activity가 어떤 산출물/component를 다루는가"만 정의합니다. 산출물 내부 component 구조와 물리 파일 정책은 artifact-standard, 실제 산출물 instance 연결은 후속 artifact 책임입니다.

하나의 Stage에서 여러 산출물 구성 요소를 작성하는 경우에는 component별 Activity output으로 분리할 수 있습니다.

Planning Phase
  Business Architecture Planning Process
    Stage: component_business_process_definition
      Activity: business_process_main_document_authoring
        output: [email protected] / main_document
      Activity: l3_process_appendix_authoring
        output: [email protected] / appendix_l3_process
      Activity: scenario_appendix_authoring
        output: [email protected] / appendix_scenario
      Activity: l4_detail_appendix_authoring
        output: [email protected] / appendix_l4_detail
      Activity: business_process_definition_consolidation
        input: main_document, appendix_l3_process, appendix_scenario, appendix_l4_detail
        output: [email protected] / main_document
        usage: refines

종합/정제처럼 여러 component를 읽고 MAIN 문서를 정제하는 작업도 Activity로 둘 수 있습니다. Stage gate/criterion은 이 Activity가 완료됐는지 판단하는 기준이고, handoff는 다음 Stage나 Process로 넘기는 관계입니다.

한 산출물 구성 요소를 작성하는 내부 절차는 Task와 Step으로 표현합니다. Task는 Activity를 완수하기 위한 업무/논리 작업 묶음이고, Step은 Task를 수행하기 위한 세부 실행 절차입니다.

Activity: 선행 산출물 입력 기준선 정의
  Task: 입력 산출물 식별
    Step: 후보 문서 목록 수집
    Step: 문서 유형 분류
    Step: 누락 또는 불명확 항목 표시

  Task: 기준선 정의서 작성
    Step: 목적 및 범위 작성
    Step: 입력 산출물 목록 표 작성
    Step: 추적 기준 작성

이 구조에서 Activity는 방법론상 활동 단위, Task는 업무/논리 중심 작업 단위, Step은 Agent/Script/Human이 수행 가능한 세부 실행 단위입니다.

Managed ID Rule

관리 ID는 DB 내부 UUID *_id나 시스템 참조용 *_code가 아니라 문서, trace, handoff, 파일명, 화면 표시에서 사용하는 사람이 읽는 식별자입니다.

methodology_identity_rules는 방법론별 formatter rule을 저장하고, 각 요소 row는 formatter 결과 또는 수동으로 확정한 값을 managed_id 계열 필드에 저장합니다. 현재 1차 모델은 자동 lock, reserved ID, 이력 테이블을 두지 않고 rule 기반 검증으로 정합성을 확인합니다.

| 대상 | 저장 필드 | Formatter 예 | | --- | --- | --- | | Phase | methodology_phases.managed_id | {phase.shortCode} | | Process | methodology_processes.managed_id | {process.identityNo:02} | | Stage | methodology_stages.managed_id | {phase.managedId}{stage.abbr} | | Activity | methodology_activities.managed_id | {stage.managedId}{activity.identityNo:02} | | Task | methodology_tasks.managed_id | {activity.managedId}-{task.identityNo:02} | | Step | methodology_steps.managed_id | {task.managedId}.{step.identityNo:02} | | Activity Primary Artifact | methodology_activity_artifact_requirements.managed_artifact_id | {activity.managedId} |

프로세스 ID와 산출물 ID는 별도 namespace입니다. 현재 Build Planning 정책에서는 Activity primary artifact가 Activity managed ID와 같은 값을 가질 수 있지만, 저장 위치와 의미는 methodology_activities.managed_id와 methodology_activity_artifact_requirements.managed_artifact_id로 분리합니다.

validateMethodologyDefinition()은 방법론 scope의 identity rule을 읽고 저장된 managed_id 또는 managed_artifact_id가 formatter 결과와 일치하는지 검증합니다.

Stage Criteria API

Stage의 시작, 종료, 전환 판단 기준은 methodology_stage_criteria와 Service API로 관리합니다.

const exitCriteria = service.createStageCriteria({
  stageId: stage.stageId,
  criteriaTypeCode: "exit",
  criteriaName: "필수 component 생성",
  criteriaText: "MAIN, L3 부록, 시나리오 부록, L4 상세 부록 component가 모두 생성되어야 한다.",
  validationRequired: true,
  severityCode: "error",
  sortOrder: 20,
  metadata: {
    criteriaCode: "exit_required_components_created"
  }
});

const criteria = service.listStageCriteriaByStage(stage.stageId);
console.log(criteria.map((item) => item.criteriaTypeCode));

구분 기준은 다음과 같습니다.

| criteriaTypeCode | 의미 | | --- | --- | | entry | Stage 시작 전 준비 조건 | | exit | Stage 종료를 위한 산출물/구조 완성 조건 | | gate | 다음 Stage 또는 승인 전환 판단 조건 |

Handoff Requirement API

Handoff는 실제 파일을 복사하거나 이동하는 기능이 아니라, 후속 Phase/Process/Stage/Activity가 입력으로 받아야 하는 산출물, 이슈, 결정, 제약 조건 등의 전달 계약입니다.

다수의 선행 산출물 component를 하나의 artifact instance 묶음으로 후행 Stage에 넘기는 경우에는 Handoff 1건에 필수 component 목록을 metadata로 둡니다.

const handoff = service.createHandoffRequirement({
  sourceScopeCode: "stage",
  sourceRefId: businessProcessStage.stageId,
  targetScopeCode: "stage",
  targetRefId: informationObjectStage.stageId,
  handoffTypeCode: "artifact",
  handoffItemName: "A컴포넌트 비즈니스 프로세스 정의서",
  handoffDescription: "컴포넌트 정보 객체 정의 Stage에서 참조할 비즈니스 프로세스 정의서 산출물 묶음이다.",
  artifactStandardCode: "business_process_definition",
  artifactStandardVersion: "1.0.0",
  validationRequired: true,
  sortOrder: 10,
  metadata: {
    handoffItemScope: "artifact_instance",
    requiredComponentCodes: [
      "main_document",
      "appendix_l3_process",
      "appendix_scenario",
      "appendix_l4_detail"
    ],
    requiredResultRefs: [
      "validation_result",
      "review_decision"
    ]
  }
});

후행 산출물을 LLM이 작성하는 경우 application 또는 runtime 조립 계층은 다음 순서로 context를 구성합니다.

1. 후행 Activity 또는 Stage 식별
2. target 기준 Handoff Requirement 조회
3. handoff metadata의 required component set 확인
4. artifact instance와 component resource link 조회
5. ADoc document 내용 조회
6. 후행 산출물의 artifact-standard 조회
7. 선행 산출물 context + 후행 산출물 표준을 LLM prompt/resource context로 조립

조회 예:

const inboundHandoffs = service.listHandoffRequirementsByTarget(
  "stage",
  informationObjectStage.stageId
);

const outboundHandoffs = service.listHandoffRequirementsBySource(
  "stage",
  businessProcessStage.stageId
);

제외 범위

| 제외 항목 | 담당 후보 | | --- | --- | | Document 내부 구조 | @soddong/agentic-domain-document | | Artifact Standard 본문 구조 | @soddong/agentic-domain-artifact-standard | | Artifact instance | @soddong/agentic-domain-artifact | | AI-Agent SDLC seed | @soddong/agentic-methodology-ai-agent-sdlc | | Runner | @soddong/agentic-runtime 또는 application package | | Render | render capability | | Adapter | @soddong/agentic-runtime |

명명 기준

| 구분 | 기준 | | --- | --- | | logical schema | methodology | | SQLite table prefix | methodology_ | | PostgreSQL mapping | 향후 중앙 DB 활용 시 methodology.* 후보 |

개발 검증

npm run build --workspace @soddong/agentic-domain-methodology
npm run typecheck --workspace @soddong/agentic-domain-methodology
npm run dev:test:agentic-domain-methodology
npm pack --workspace @soddong/agentic-domain-methodology --dry-run --cache /private/tmp/agentic-npm-cache

기본 API 예시

import {
  applyAgenticSeed,
  getMethodologyPackageInfo,
  initializeMethodologyDatabase,
  openMethodologyDatabase,
  MethodologyService,
  seedBuildPlanningExample,
  validateMethodologyDefinition
} from "@soddong/agentic-domain-methodology";

console.log(getMethodologyPackageInfo());

const result = initializeMethodologyDatabase({
  projectRoot: process.cwd()
});

console.log(result.tables);

const db = openMethodologyDatabase({ projectRoot: process.cwd() });
const service = new MethodologyService(db);

const scenario = service.createDefinitionScenario({
  methodology: {
    methodologyCode: "sdlc_default",
    methodologyName: "기본 SDLC 방법론",
    methodologyVersion: "1.0.0"
  },
  lifecycle: {
    lifecycleCode: "default_lifecycle",
    lifecycleName: "기본 Lifecycle"
  },
  phase: {
    phaseCode: "analysis",
    phaseName: "분석"
  },
  process: {
    processCode: "requirements_management",
    processName: "요구사항 관리"
  },
  activity: {
    activityCode: "requirements_definition",
    activityName: "요구사항 정의"
  }
});

console.log(scenario.activity.activityId);

const validation = validateMethodologyDefinition(db);
console.log(validation.valid);
db.close();

Process 추가 API 사용 기준

Process는 특정 Lifecycle에 직접 종속되는 데이터가 아니라 Methodology에 종속됩니다. Phase와 Process의 관계는 methodology_phase_processes 연결 테이블로 표현합니다.

따라서 이미 생성된 Lifecycle 또는 Phase를 기준으로 Process를 추가할 때는 createProcess()에 lifecycleId를 넘기지 않습니다.

잘못된 예:

service.createProcess({
  lifecycleId: scenario.lifecycle.lifecycleId,
  processCode: "architecture_design",
  processName: "아키텍처 설계"
});

createProcess()는 methodologyId를 직접 받는 저수준 API입니다.

service.createProcess({
  methodologyId: scenario.methodology.methodologyId,
  processCode: "architecture_design",
  processName: "아키텍처 설계"
});

consumer 코드에서 Lifecycle 기준으로 Process를 추가하고 싶다면 createProcessForLifecycle()을 사용합니다.

const process = service.createProcessForLifecycle({
  lifecycleId: scenario.lifecycle.lifecycleId,
  processCode: "architecture_design",
  processName: "아키텍처 설계"
});

Phase 기준으로 Process를 만들고 Phase에 바로 배정하려면 createProcessForPhase()를 사용합니다.

const result = service.createProcessForPhase({
  phaseId: scenario.phase.phaseId,
  processCode: "architecture_design",
  processName: "아키텍처 설계",
  phaseProcess: {
    sortOrder: 20
  }
});

console.log(result.process.processId);
console.log(result.phaseProcess.phaseProcessId);

조회/탐색 API 예시

생성된 방법론 구조를 확인할 때는 직접 SQL을 작성하기보다 Service 조회 API를 우선 사용합니다.

단위 목록 조회:

const lifecycles = service.listLifecyclesByMethodology(scenario.methodology.methodologyId);
const phases = service.listPhasesByLifecycle(scenario.lifecycle.lifecycleId);
const processes = service.listProcessesByPhase(scenario.phase.phaseId);
const activities = service.listActivitiesByProcess(scenario.process.processId);
const stages = service.listStagesByProcess(scenario.process.processId);
const tasks = service.listTasksByActivity(scenario.activity.activityId);
const steps = service.listStepsByActivity(scenario.activity.activityId);
const taskSteps = service.listStepsByTask(tasks[0].taskId);
const outputs = service.listActivityArtifactRequirements(scenario.activity.activityId);

전체 구조 조회:

const structure = service.getMethodologyStructure(scenario.methodology.methodologyId);

for (const lifecycle of structure.lifecycles) {
  for (const phase of lifecycle.phases) {
    for (const process of phase.processes) {
      console.log(process.process.processName);
      console.log(process.activities.map((item) => item.activity.activityName));
      console.log(process.activities.flatMap((item) => item.tasks.map((task) => task.task.taskName)));
      console.log(process.stages.map((item) => item.stage.stageName));
    }
  }
}

getMethodologyStructure()는 Methodology -> Lifecycle -> Phase -> Process -> Activity/Task/Step/Stage 구조를 읽기 위한 편의 read model입니다. Stage 하위 Activity는 methodology_stage_activities 연결 기준으로 조회되며, Activity 하위 Task/Step은 methodology_tasks, methodology_steps 기준으로 조회됩니다.

Fixture/Seed 사용 예시

seedBuildPlanningExample()은 temp/ 아래 Build Planning 방법론 정리 내용을 기준으로 구성한 예시 데이터를 생성합니다.

포함 범위:

• Build Planning Phase
• Build Planning Process
• 분석
• 상위 설계
• 구조 설계
• Build 범위 계획
• 개발 단위 계획
• Stage별 대표 Activity, Task, Step, primary output artifact requirement
• 특정 Stage에 종속되지 않는 Cross-cutting Governance Activity

참고: 공식 Build Planning fixture는 분석, 상위 설계, 구조 설계 Stage를 포함하며, 후속 Stage로 Build 범위 계획과 개발 단위 계획을 둡니다. 기존 Build Scope Planning Stage의 Gate/Handoff 성격 활동은 Build 실행 계획 수립, Handoff Requirement, 개발 단위 실행 입력 기준 정의로 재배치했습니다.

사용 예:

const seedResult = seedBuildPlanningExample(db);

console.log(seedResult.seeded);
console.log(seedResult.structure.methodology.methodologyName);
console.log(seedResult.structure.lifecycles[0].phases[0].processes[0].stages.length);
console.log(seedResult.structure.lifecycles[0].phases[0].processes[0].activities.length);

동일한 methodologyCode + methodologyVersion이 이미 존재하면 중복 생성하지 않고 기존 구조를 반환합니다.

const first = seedBuildPlanningExample(db);
const second = seedBuildPlanningExample(db);

console.log(first.seeded);  // true
console.log(second.seeded); // false

Runtime Seed Apply Handler

applyAgenticSeed()는 @soddong/agentic-runtime seed apply가 target package를 호출할 때 사용하는 handler입니다.

이 handler는 methodology 도메인이 소유하는 section만 처리합니다.

| sourceSection | 처리 | | --- | --- | | methodology | Methodology 생성 또는 기존 항목 skip | | identityRules | 방법론 요소별 managed ID formatter rule 생성 | | lifecycle | Lifecycle 생성 또는 기존 항목 skip | | phases | Phase 목록 생성 | | processes | Process 생성 및 Phase 연결 | | stages | Stage 목록 생성 | | activities | Activity 생성 및 Stage 연결 | | tasks | Activity 하위 업무/논리 Task 생성 | | steps | Task 하위 세부 실행 Step 생성 | | activityArtifactRequirements | Activity output/input/supporting artifact requirement 생성 | | criteria | Stage criteria 생성 | | handoffs | Stage 간 handoff requirement 생성 |

identityRules seed는 methodology section 뒤, 요소 seed 이전에 적용하는 것을 권장합니다. phases, processes, stages, activities, tasks, steps는 managedId와 identityNo를 수용하고, activityArtifactRequirements는 산출물 namespace의 managedArtifactId를 수용합니다.

tasks seed는 activityCode + taskCode를 기준으로 기존 항목을 식별합니다. steps seed는 taskCode만으로도 처리할 수 있지만, 같은 methodology 안에서 Task code가 재사용될 수 있으므로 신규 bundle은 activityCode + taskCode + stepCode를 함께 제공하는 것을 권장합니다.

generatedOutputLinks, validationProfiles, sampleExecution은 각각 artifact-standard, validation, artifact 계열 패키지의 책임입니다.

예시:

await applyAgenticSeed({
  sourcePackageName: "@soddong/agentic-methodology-ai-agent-sdlc",
  sourcePackageVersion: "0.2.0",
  bundleCode: "ai-agent-sdlc-build-planning",
  bundleVersion: "0.2.0",
  methodologyCode: "ai_agent_sdlc",
  sourceSection: "stages",
  targetOperation: "upsert_stages",
  mode: "apply",
  itemPayload: [
    {
      processCode: "build_planning_process",
      stageCode: "analysis_stage",
      stageName: "Analysis Stage",
      stageTypeCode: "analysis",
      stageOrder: 10
    }
  ]
});

적용 결과는 다음 중 하나를 반환합니다.

| status | 의미 | | --- | --- | | applied | 신규 methodology 데이터가 생성됨 | | skipped | 동일 기준의 데이터가 이미 있어 중복 생성하지 않음 | | blocked | 선행 methodology, lifecycle, phase, process, stage, activity 등이 없어 적용할 수 없음 | | failed | payload 필수값 누락 또는 DB 제약 오류 |

AI-Agent SDLC seed의 handoffTypeCode: "stage_gate"는 현재 methodology DB의 공통 handoff type에 직접 포함되지 않으므로 context로 저장합니다. 원본 stage_gate 값은 metadata의 seedPayload에 보존합니다.

Validation Scope 사용 예시

validateMethodologyDefinition(db)는 기본적으로 methodology DB 전체를 검증합니다. 하나의 consumer 프로젝트 안에 여러 방법론, 테스트 데이터, 의도적으로 만든 오류 데이터가 함께 있을 수 있으므로 특정 방법론만 검증해야 할 때는 scope를 지정합니다.

방법론 ID 기준:

const result = validateMethodologyDefinition(db, {
  scope: {
    methodologyId: seedResult.methodologyId
  }
});

console.log(result.valid);

방법론 코드와 버전 기준:

const result = validateMethodologyDefinition(db, {
  scope: {
    methodologyCode: "build_planning_example",
    methodologyVersion: "1.0.0"
  }
});

console.log(result.valid);

전체 validation은 DB 안의 모든 방법론과 테스트 데이터를 함께 검증합니다. 특정 fixture나 특정 방법론의 품질만 확인하려면 scoped validation을 사용합니다.

기대 결과:

{
  "name": "@soddong/agentic-domain-methodology",
  "version": "0.11.5",
  "layer": "domain",
  "logicalSchema": "methodology",
  "sqliteTablePrefix": "methodology_",
  "cli": "not-provided",
  "adapter": "not-provided"
}