agentic-domain-methodology

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

이 패키지는 Methodology, Lifecycle, Phase, Process, Stage, Activity, 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, 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를 참조 가능 | | Stage Criteria API | Stage entry/exit/gate 기준 생성/조회 가능 | | Handoff Requirement API | 수행 단위 간 전달 계약 생성/조회 가능 | | Runtime Seed Apply Handler | AI-Agent SDLC seed의 methodology section 적용 가능 | | Validator | 최소 구조 정합성 검증 포함 | | Fixture/Seed | Build Planning 예시 포함 | | Agent contribution | 후속 iteration | | CLI | 1차 구현 제외 | | Adapter | 1차 구현 제외 |

도메인 책임

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

Activity Artifact Requirement와 Document Component 참조

methodology는 산출물 표준 내부 구조를 직접 소유하지 않습니다. 본문, 부록, 하위 부록 같은 산출물 구성 단위는 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로 넘기는 관계입니다.

한 산출물 구성 요소를 작성하는 내부 절차는 Step으로 표현할 수 있지만, 현재 조립 검증에서는 Step까지 세분화하지 않습니다.

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 내부 구조 | agentic-domain-document | | Artifact Standard 본문 구조 | agentic-domain-artifact-standard | | Artifact instance | agentic-domain-artifact | | AI-Agent SDLC seed | agentic-methodology-ai-agent-sdlc | | Runner | agentic-runtime 또는 application package | | Render | render capability | | Adapter | agentic-runtime |

명명 기준

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

개발 검증

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

기본 API 예시

import {
  applyAgenticSeed,
  getMethodologyPackageInfo,
  initializeMethodologyDatabase,
  openMethodologyDatabase,
  MethodologyService,
  seedBuildPlanningExample,
  validateMethodologyDefinition
} from "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 steps = service.listStepsByActivity(scenario.activity.activityId);
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.stages.map((item) => item.stage.stageName));
    }
  }
}

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

Fixture/Seed 사용 예시

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

포함 범위:

• Build Planning Phase
• Build Planning Process
• Analysis Stage
• Interface Design Stage
• Structure Design Stage
• Build Scope Planning Stage
• Stage별 대표 Activity, Step, primary output artifact requirement
• 특정 Stage에 종속되지 않는 Cross-cutting Governance Activity

사용 예:

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()는 agentic-runtime seed apply가 target package를 호출할 때 사용하는 handler입니다.

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

| sourceSection | 처리 | | --- | --- | | methodology | Methodology 생성 또는 기존 항목 skip | | lifecycle | Lifecycle 생성 또는 기존 항목 skip | | phases | Phase 목록 생성 | | processes | Process 생성 및 Phase 연결 | | stages | Stage 목록 생성 | | activities | Activity 생성 및 Stage 연결 | | activityArtifactRequirements | Activity output/input/supporting artifact requirement 생성 | | criteria | Stage criteria 생성 | | handoffs | Stage 간 handoff requirement 생성 |

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

예시:

await applyAgenticSeed({
  sourcePackageName: "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": "agentic-domain-methodology",
  "version": "0.11.1",
  "layer": "domain",
  "logicalSchema": "methodology",
  "sqliteTablePrefix": "methodology_",
  "cli": "not-provided",
  "adapter": "not-provided"
}