@soddong/agentic-methodology-ai-agent-sdlc

@soddong/agentic-methodology-ai-agent-sdlc는 Agentic Platform에서 사용할 AI-Agent SDLC 방법론 seed bundle package입니다.

이 패키지는 공통 메타모델을 새로 정의하지 않습니다. 대신 @soddong/agentic-domain-methodology, @soddong/agentic-domain-artifact-standard, @soddong/agentic-domain-artifact, @soddong/agentic-domain-document, @soddong/agentic-contract-validation 위에 적재할 방법론 seed/catalog를 제공합니다.

현재 범위

0.2.46는 Build Planning Phase seed bundle 0.2.46, Windows loader path fix, Git transfer-safe runtime hook wrapper 기준선, 방법론 managed ID rule seed, 공식/리허설 Lifecycle Model seed를 포함합니다. 현재 실행 시작점은 공식 착수 전 리허설/교육용 Lifecycle이며, 이 리허설은 상세 설계까지 포함한 Build Planning 흐름을 수행한다. 공식 Lifecycle Model에는 실제 계획 기준으로 Build Planning과 Build Dev. #1~#3 skeleton을 포함한다. 공식 Build Planning은 상세 설계를 포함하지 않고 Build 범위 계획과 개발 단위 계획 Stage를 포함하며, 리허설 Build Planning은 상세 설계를 포함한다. Build Dev. #1~#3는 Stage skeleton까지 포함하며, 상세 Activity/Task/Step과 Release는 후속 범위입니다. 현재 단계에서는 bundle 이름을 ai-agent-sdlc-build-planning으로 유지하고, 후속에 ai-agent-sdlc로 rename한다. 전체 SDLC 상세 bundle로 확장하지 않은 상태에서 공식 Lifecycle skeleton과 리허설 기반 Build Planning seed의 실행 가능성을 먼저 높입니다.

| 구분 | 상태 | | --- | --- | | package skeleton | 포함 | | TypeScript loader/validator | 포함 | | seed bundle manifest | 포함 | | Build Planning Phase catalog | 포함 | | activity/criteria/handoff/artifact requirement | 포함 | | identity-rules / managed ID | 포함 | | phase/process entry/exit criteria | 후속 | | activity completion criteria | 포함 | | activity input artifact requirement | 포함 | | generated output link | 포함 | | validation profile | 포함 | | sample execution | 포함 | | Project Scaffolding Profile 연계 | @soddong/[email protected] 이상에서 지원 | | project create/status | 포함 | | Build Dev. #1~#3 Stage skeleton | 포함 | | Build Development 개발 수행/통합 테스트 Activity/Task/Step | 포함 | | Build Development 조정/구체화 Stage 상세 Activity/Task/Step | 후속 | | Build 범위 계획 Stage | 포함 | | Release | 후속 |

명명 기준

| 항목 | 값 | | --- | --- | | 공식 방법론명 | AI-Agent SDLC | | package | @soddong/agentic-methodology-ai-agent-sdlc | | methodology code | ai_agent_sdlc | | seed bundle | ai-agent-sdlc-build-planning 현재 유지, 후속 ai-agent-sdlc rename 예정 |

사용 예시

import {
  getAiAgentSdlcPackageInfo,
  listAiAgentSdlcBundles,
  loadAiAgentSdlcBundle,
  validateAiAgentSdlcBundle
} from "@soddong/agentic-methodology-ai-agent-sdlc";

console.log(getAiAgentSdlcPackageInfo());
console.log(listAiAgentSdlcBundles());

const bundle = loadAiAgentSdlcBundle("ai-agent-sdlc-build-planning");
console.log(validateAiAgentSdlcBundle(bundle).valid);

방법론 내용 확인

JSON seed를 직접 보지 않고 방법론 구조를 검토하려면 docs/methodology-overview.md를 확인한다.

Lifecycle Model과 프로세스/산출물 ID 체계는 docs/methodology-identity-model.md를 확인한다. 실행 산출물과 가이드 산출물의 세부 ID 체계는 docs/artifact-id-model.md를 확인한다.

Seed 포함 범위와 후속 범위는 docs/seed-coverage.md를 확인한다.

OS별 파일명/경로 호환성 기준은 docs/cross-platform-compatibility.md를 따른다.

Seed JSON, 정적 문서 생성, Execution Project SQLite 조회 원천의 책임 구분은 docs/source-and-rendering-architecture.md를 따른다.

Seed/Bundle Project와 Execution Project에서 Workbench가 제공해야 하는 화면, 조회 원천, 모드 구분은 docs/workbench-project-modes.md를 따른다.

Execution Project에서 DBMS 없이 설치된 seed package 기준으로 방법론 튜토리얼을 확인하는 기준은 docs/tutorial-mode.md를 따른다.

프로젝트 자체의 작업 관리, 변경 반영, 검증, publish 판단 기준은 docs/project-work-management.md를 따른다.

Platform 패키지 갱신은 방법론·seed 재생성과 분리한다. npm run platform:update -- --manifest <path>는 Platform release manifest 중 이 Bundle/Seed가 직접 사용하는 Runtime, Domain, Capability, Contract, Workbench 의존성만 변경하고 보호 데이터 hash를 확인한다. npm run platform:verify는 현재 seed schema 호환성을 검사한다. 방법론 원천 변경 또는 승인된 migration이 있을 때만 npm run seed:regenerate를 실행한다. 상세 기준은 Seed schema migration을 따른다.

신규 Bundle package를 publish할 때는 npm run version:bump -- patch로 Package, Bundle, Methodology 버전을 함께 증가시킨다. Platform workspace package의 버전은 Platform 저장소에서 별도로 관리한다.

Seed JSON은 공식 Lifecycle Model incremental_build_lifecycle과 사전 리허설/교육용 Lifecycle Model _incremental_build_lifecycle_rehearsal을 함께 제공한다. 현재 bundle 실행 scope는 rehearsal Lifecycle이며, 리허설은 공식 시작 전에 상세 설계까지 포함한 Build Planning 흐름을 수행한다. 공식 Lifecycle은 실제 계획 기준으로 BP, B1, B2, B3 Phase와 Stage skeleton을 포함하며, 공식 BP는 분석 -> 상위 설계 -> 구조 설계 -> Build 범위 계획 -> 개발 단위 계획 흐름을 가진다. 공식 tree는 기존 non-underscore code를 유지하고, 임시 tree는 _ prefix system code를 사용한다. Seed JSON은 identity-rules.json과 각 요소의 managedId, identityNo, stageAbbr, shortCode, managedArtifactId를 함께 제공한다. Process managed ID와 Artifact managed ID는 별도 namespace이며, 현재 Build Planning에서는 Activity primary artifact의 managedArtifactId가 Activity managedId와 같은 값을 갖는다. 실행 산출물 본문은 .M, 부록은 .A01, 가이드 산출물은 .G01 개념 및 기법서, .G02 서식 및 가이드, .G03 예시로 구분한다.

Seed JSON 기준의 상세 카탈로그와 Mermaid 다이어그램은 다음 명령으로 생성한다.

npm run docs:seed

생성 결과는 docs/generated/ai-agent-sdlc-build-planning/ 아래에 위치한다.

브라우저에서 사용자 친화적으로 보려면 다음 파일을 연다.

docs/generated/ai-agent-sdlc-build-planning/index.html
docs/generated/ai-agent-sdlc-build-planning/tutorial.html

Workbench UI

Bundle/Seed authoring UI는 published Workbench package를 dev dependency로 설치해 이 프로젝트 root에서 실행한다.

npm install
npm run workbench:authoring

기본 URL은 다음과 같다.

http://127.0.0.1:4783

Workbench 설정 원천은 ui/workbench.config.json이며, Bundle/Seed 프로젝트에서는 experienceMode: authoring을 사용한다. tree의 Stage 이름은 분석, 상위 설계, 구조 설계, Build 범위 계획, 개발 단위 계획처럼 업무명만 두고, 계층 표시는 Workbench badge가 담당한다.

Execution Project에서는 authoring 원천을 직접 보지 않는다. Execution Tutorial Mode는 execution project에 설치된 seed package를 read-only로 조회하며 DBMS를 사용하지 않는다. 실행 상태, 산출물 생성 상태, 검증 결과, 실행 로그를 포함하는 Execution View는 project create 또는 bundle apply 이후 .agentic/platform.sqlite에 적재된 데이터를 기준으로 조회하는 범위다.

Execution Project에서 설치된 seed package 기준의 튜토리얼을 열려면 다음을 실행한다.

npm install @soddong/agentic-methodology-ai-agent-sdlc@<version>
npx --no-install agentic-methodology-ai-agent-sdlc-tutorial --port 4791

이 wrapper는 내부적으로 설치된 seed package root를 Workbench --project로 지정하고 --mode tutorial을 강제한다. 따라서 튜토리얼 모드에서는 project create, bundle apply, .agentic/platform.sqlite 갱신이 필요하지 않다.

Execution Project 적용

기존 프로젝트 자동 갱신

Workbench를 종료한 후 Execution Project root에서 다음 한 줄을 실행한다.

npx --yes -p @soddong/agentic-methodology-ai-agent-sdlc@latest \
  agentic-methodology-ai-agent-sdlc-update

배포 패키지에 포함된 update CLI가 DB를 먼저 백업하고 패키지 설치, module migration, Bundle content 비교 및 필요한 seed 갱신을 수행한다. 상세 절차는 운영 가이드를 따른다.

최초 실행 후에는 execution package.json에 갱신 명령이 등록되므로 다음부터는 npm run bundle:update만 실행한다.

변경 유형별 예상 조치를 먼저 확인하려면 npm run bundle:update -- --plan을 사용한다. Workbench-only 변경은 DB backup, migration, seed apply 없이 package만 갱신한다.

0.2.46 이전 updater에서 최초 전환할 때는 npx --yes -p @soddong/[email protected] agentic-methodology-ai-agent-sdlc-update --plan으로 신규 updater를 직접 실행한다.

Bundle release version은 실제 seed 변경 여부에 따라 구분한다. Seed 변경은 npm run version:bump -- patch, transport 코드·UI·문서만 변경된 경우는 npm run version:bump -- patch --transport-only를 사용한다.

Production NOVA SDD Bundle은 projectCreation.mode=SCAFFOLDING_PROFILE이며 단일 defaultProject를 제공하지 않는다. 일반 agentic project create는 대상 프로젝트를 변경하기 전에 거부된다. L2 Physical Project와 L2.5별 Runtime Execution Project는 아래 전용 wrapper로만 생성한다.

npx --yes -p @soddong/agentic-methodology-ai-agent-sdlc@<target-version> agentic-methodology-ai-agent-sdlc-create --component-id TMFC028 --project-root ./execution-project

--component-id는 SSF v2 L2 managedCode이며 존재하지 않으면 파일과 DB를 생성하지 않는다. --plan은 무변경 계획, --resume은 Binding이 완전히 일치하는 DB에서만 물리화를 재개한다. 직계 L2.5마다 독립 Runtime Execution Project를 같은 DB에 생성한다. Artifact 폴더와 선행 입력 데이터는 생성·설치하지 않는다. 세부 기준은 운영 가이드를 따른다.

생성 완료 시 Bundle과 requires.runtime은 execution installation의 direct exact dependency로 물리화되며, project-local node_modules/.bin/agentic CLI가 제공되어야 한다. 생성 후 별도 Runtime 설치가 필요한 상태는 완료로 간주하지 않는다.

기본 출력은 Component, Execution Unit, Runtime Project와 디렉터리 수를 보여주는 사용자용 요약이다. 실제 생성 성공·실패와 --resume도 요약하며 실패 시 오류 코드, 마지막 성공 단계, DB 보존 여부와 재개 방법을 표시한다. 자동화나 상세 검토를 위해 전체 구조 결과가 필요하면 --format json을 사용한다. --plan은 출력 형식과 관계없이 대상 파일과 DB를 변경하지 않는다.

Troubleshooting

npx agentic ...는 npm의 별도 package인 agentic을 실행할 수 있다. 이 package는 @soddong/agentic-runtime CLI가 아니므로 project create를 지원하지 않을 수 있다.

BUNDLE.SCAFFOLDING_ENTRYPOINT_REQUIRED가 발생하면 generic project create가 아니라 위 전용 wrapper를 사용한다.

Unknown command: project create ...

Windows에서 AI-Agent SDLC seed manifest not found: /C:/... 또는 C:\... 경로 탐색 오류가 발생하면 @soddong/[email protected] 이상을 사용한다. 0.2.9는 Windows에서 file URL pathname을 직접 사용해 seed 파일 탐색에 실패할 수 있다.

Git repository로 전달받은 execution project에서 Stop hook (failed)와 hook exited with code 1이 발생하면 stale .agentic/bin/agentic-hook.mjs가 commit됐는지 확인한다. @soddong/[email protected] 이상은 setup 또는 adapter install 시 .agentic hook wrapper와 .gitignore managed block을 재생성한다.

npm install
npx --yes -p @soddong/[email protected] agentic setup --adapter codex --force