Kiro 에이전트와 Harness Engineering: LGU+ Knowledge-based Mass Migration 자동화

국내 주요 통신사업자인 LG U+는 모바일, 홈(IPTV/IoT), 기업 서비스 등 다양한 사업 영역에서 서비스를 제공하고 있습니다. 이러한 서비스들을 뒷받침하는 백엔드 시스템은 오랜 기간 온프레미스 환경에서 구축·운영되어 왔으며, 서비스 간 의존성과 레거시 기술 스택이 복잡하게 얽혀 있습니다. LG U+는 시장 변화에 민첩하게 대응하고 인프라 운영 효율을 높이기 위해, 이 중 약 100개의 서비스를 AWS 클라우드로 전환하기로 결정했습니다.
이 마이그레이션은 단순한 리프트 앤 시프트가 아닙니다. Java 버전 및 Spring Framework, 공통 라이브러리 업그레이드, 시크릿 관리 체계 전환, 세션 스토어 외부화, 파일 스토리지 S3 전환, Altibase에서 Amazon Aurora MySQL로, Oracle에서 Amazon Aurora PostgreSQL로의 DB 마이그레이션 등 서비스마다 수십 개의 전환 작업이 필요합니다. 특히 온프레미스 환경에서 독립적으로 운영되던 배치 시스템, 인메모리 세션 스토어 같은 구성 요소들은 AWS 퍼블릭 클라우드 환경의 관리형 서비스(Amazon ElastiCache, Amazon S3, Amazon Aurora 등)를 활용하는 구조로 재설계해야 했습니다. 약 100개의 서비스를 수십 개 협력 개발사가 동시에 전환해야 하는 규모이므로, 일관된 품질과 속도를 유지하는 것이 핵심 과제였습니다.

LG U+ 클라우드 전환팀은 이 과제를 AWS Professional Services 조직과 함께 수행하며, 다양한 AI 도구를 활용했습니다. 소스코드 분석 및 코드 변환 자동화에는 AWS Transform Custom, 설계 문서 생성에는 Amazon Bedrock 기반 Agent를, 그리고 개발자가 직접 참여하는 전환 작업에는 AI 코딩 어시스턴트 Kiro를 사용했습니다. 이 글은 그 중 Kiro를 활용한 전환 작업 영역에 집중합니다. 개발자 간 AI 활용 격차, 조직 지식의 컨텍스트 반영, 전환 경험의 재사용이라는 과제를 Harness Engineering 환경을 접목하여 어떻게 풀어냈는지 소개합니다.

AI를 도입했는데, 왜 결과가 사람마다 다를까?

AI 코딩 어시스턴트의 등장으로 개발 생산성이 비약적으로 향상되고 있습니다. 하지만 실제 조직에 AI를 도입해보면 한 가지 불편한 진실과 마주하게 됩니다. 같은 도구를 써도, 사람마다 결과물의 품질이 너무 다릅니다.

어떤 개발자는 Custom Agent, Steering, Skill 같은 고급 설정을 능숙하게 활용하여 일관된 품질의 코드를 뽑아내고, 어떤 개발자는 기본 설정 그대로 사용하며 AI의 잠재력을 절반도 끌어내지 못합니다. 프롬프트 하나의 차이로 결과물의 수준이 갈리기도 합니다.

여기에 더 근본적인 문제가 있습니다. 대규모 조직에는 오랜 시간에 걸쳐 축적된 기술 표준, 보안 정책, 아키탁처 컨벤션, 전환 노하우가 존재합니다. 하지만 이 지식들은 Confluence 어딘가의 문서, 특정 팀원의 머릿속, 과거 프로젝트의 코드 안에 흩어져 있어서 실제 개발 현장까지 전달되지 않는 경우가 많습니다. AI 도구를 도입해도 이 조직 지식이 AI의 컨텍스트에 반영되지 않으면, 결국 표준을 모르는 상태에서 코드를 생성하게 됩니다. 개인 프로젝트라면 이 정도 편차는 문제가 되지 않습니다. 하지만 약 100개의 서비스를 수십 개 개발사가 동시에 전환하는 대규모 마이그레이션 프로젝트라면 이야기가 달라집니다. 개발자 간 AI 활용 성숙도의 차이가 곧 전체 프로젝트의 품질 편차로 이어지고, 이는 일정 지연과 재작업 비용으로 돌아옵니다.

배경: 우리가 풀어야 했던 문제

저희 프로젝트는 온프레미스 환경의 레거시 서비스들을 AWS 클라우드로 전환하는 대규모 마이그레이션입니다. 전환 대상은 약 100개의 서비스이며, 각 서비스마다 Java 버전 업그레이드, 시크릿 관리 전환, 세션 스토어 외부화, 파일 스토리지 S3 전환, DB 마이그레이션 등 다양한 작업이 필요합니다. 이 규모의 전환을 체계적으로 진행하기 위해, 전체 프로세스를 크게 두 단계로 나누었습니다.

1. Assessment 단계에서는 AI Agent들이 각 서비스의 현황을 파악하고, 소스코드를 분석하여 전환이 필요한 항목(Action Item)을 도출하며, To-Be 아키텍처를 설계합니다. 이 단계의 산출물 — 분석 리포트, 설계 문서, Action Item 목록 등 — 은 중앙 저장소에 업로드되어 웹 페이지에서 조회할 수 있습니다. Assessment의 핵심 산출물 중 하나가 서비스별 Action Item 목록(action_items.json)입니다. 이 파일에는 해당 서비스에서 수행해야 할 전환 작업들이 구조화되어 있습니다.

action_items.json (샘플)

{
  "project_name": "order-service",
  "action_items": [
    {
      "id": "act-001",
      "title": "Java 17 업그레이드",
      "category": "upgrade",
      "difficulty": "low",
      "description": "Java 8에서 Java 17로 업그레이드. deprecated API 교체 및 빌드 설정 변경"
    },
    {
      "id": "act-002",
      "title": "세션 스토어 Valkey 전환",
      "category": "session-store",
      "difficulty": "high",
      "description": "인메모리 HttpSession을 ElastiCache Valkey 외부 세션 스토어로 전환"
    },
    {
      "id": "act-003",
      "title": "파일 스토리지 S3 전환",
      "category": "file-storage",
      "difficulty": "medium",
      "description": "로컬 파일시스템/NAS 기반 파일 저장을 Amazon S3로 전환"
    },
    {
      "id": "act-004",
      "title": "Altibase → Aurora MySQL 쿼리 변환",
      "category": "database",
      "difficulty": "high",
      "description": "Altibase 전용 SQL 구문을 Aurora MySQL 호환 쿼리로 변환"
    }
  ]
}

2. Migration 단계에서는 Assessment의 산출물을 입력으로 받아, 실제 코드 전환(Transform), 검증(Test)을 수행합니다. 이 중 패턴이 일정한 단순 작업(Java 버전 업그레이드, 하드코딩 시크릿 제거)은 자동화 Agent가 처리할 수 있습니다. 하지만 세션 스토어 전환, 파일 스토리지 S3 마이그레이션, DB 쿼리 변환, 배치 스케줄러 통합 같은 작업은 서비스마다 비즈니스 로직이 다르고, 설계 판단이 필요하며, 자동화만으로는 해결되지 않습니다.

이 글은 바로 이 영역, Migration 단계의 Transform 중에서도 개발자가 AI(Kiro)와 협업하여 수행하는 전환 작업에 집중합니다. 그리고 여기서 두 가지 문제가 발생했습니다.

문제1: 설정의 장벽

Kiro는 Custom Agent, Steering, Skill, Power(MCP 서버) 등 강력한 확장 기능을 제공합니다. 하지만 이 기능들을 제대로 활용하려면 올바른 디렉토리 구조에 올바른 설정 파일을 배치해야 하고, 각 설정이 어떤 역할을 하는지 이해해야 합니다. 성숙도가 높은 개발자는 이 설정들을 능숙하게 구성하여 AI의 성능을 극대화하지만, 그렇지 않은 개발자는 설정 자체를 모르거나 잘못 구성하여 AI 기능을 충분히 활용하지 못합니다.

문제2: 프롬프트 품질의 격차

설정을 잘 했다 하더라도, AI에게 어떤 맥락을 주고 어떤 순서로 작업을 지시하느냐에 따라 결과물의 품질이 크게 달라집니다. 경험 많은 개발자는 요구사항을 체계적으로 정리하고, 관련 컨텍스트를 적절히 제공하며, 단계별로 검증하면서 작업을 진행합니다. 반면 경험이 적은 개발자는 모호한 지시로 시작하여 시행착오를 반복하게 됩니다.
약 100개의 서비스 × 수십 개 개발사 × 서비스당 수십 개 Action Item — 이 조합에서 개발자마다 다른 설정, 다른 프롬프트 품질은 전체 프로젝트의 품질 편차를 감당할 수 없는 수준으로 키웁니다.

해결 방법: Harness Engineering

AI 에이전트 시대에서 Harness(하네스)란, 모델(LLM) 바깥에서 에이전트가 안정적으로 일하도록 둘러싼 운영 장치 전체를 의미합니다. 모델이 똑똑한 작업자라면, 하네스는 그 작업자가 일하는 작업 환경과 안전장치이고, Harness Engineering은 그 작업 환경을 설계하는 일입니다. 좋은 모델만 있다고 끝나는 게 아닙니다. 그 모델이 제대로 일하게 하려면 다음이 필요합니다.

• 어떤 문서를 먼저 읽을지 — 요구사항, 설계 문서, 코드베이스, 표준, 과거 결정사항 중 무엇을 컨텍스트로 줄 것인가 (Context 설계)
• 어떤 도구를 어떤 순서로 쓸 수 있는지 — 검색, 코드 수정, 테스트 실행, 문서 생성 등 도구 호출을 어떻게 오케스트레이션할 것인가 (Tool/Workflow 오케스트레이션)
• 어떤 규칙을 반드시 지켜야 하는지 — 아키텍처 규칙, 스타일 규칙, 보안 정책, 승인 절차 같은 제약을 어떻게 강제할 것인가 (Guardrail/Constraint 설계)
• 결과를 어떤 기준으로 검증할지 — 테스트, lint, diff review, human review 같은 검증 장치와 피드백 루프를 어떻게 구성할 것인가 (검증과 피드백 루프)
• 중간 결과를 어디에 저장할지 — 작업 상태, 중간 산출물, 문서, 커밋, 로그를 어떻게 관리할 것인가 (상태/산출물 관리). 저희 파이프라인에서는 분석/설계 Agent의 산출물이 중앙 저장소(S3)에 업로드되어 웹 페이지에서 조회되고, 전환 작업의 결과물은 Skill-`confluence-doc-generator`를 통해 Confluence에 표준 문서로 자동 적재됩니다
• 잘못된 방향으로 가면 어떻게 되돌릴지 — 롤백, 복구, 에러 핸들링을 어떻게 설계할 것인가 (Recovery 설계)

Harness Engineering은 “AI가 코드를 잘 쓰게 만드는 기술”이라기보다, “AI가 실제 조직의 일을 망치지 않고 반복 가능하게 수행하도록 만드는 시스템 설계”입니다.

저희는 이 개념을 대규모 마이그레이션이라는 실무 맥락에 적용했습니다. 핵심 아이디어는 세 가지입니다.

1. 로컬 Knowledge Hub — 조직이 축적한 기술 표준, 보안 정책, 전환 패턴, 아키텍처 컨벤션을 AI가 이해할 수 있는 구조(Skill, Steering, Power, Custom Agent)로 정리하고, 이를 개발자의 로컬 workspace에 직접 세팅합니다. 중앙 위키나 RAG 시스템에 지식을 두고 검색하는 방식과 달리, AI 에이전트의 컨텍스트 안에 조직 지식이 내장되므로 별도의 검색 없이도 코드 생성 시점에 자동으로 반영됩니다. 개발자가 조직의 표준을 몰라도, AI가 이미 알고 있는 상태에서 작업을 시작합니다.
2. 설정의 자동화 — Knowledge Hub 설정(Custom Agent, Steering, Skill, Power)을 CLI 한 줄로 개발자의 workspace에 세팅합니다. 에이전트가 읽어야 할 문서, 사용할 도구, 지켜야 할 규칙이 한 번에 구성됩니다.
3. 플로우의 패턴화 — AI를 활용한 작업 흐름(요구사항 작성 → 설계 → 구현 → 검증 → 지식 자산화)을 식별하고, 각 단계를 시스템 명령어로 녹여서 누구나 동일한 품질의 프로세스를 밟도록 합니다. 검증과 피드백 루프, 산출물 관리까지 플로우 안에 내장됩니다.

Harness 구성 요소

Harness Engineering은 Knowledge Hub와 CLI Tool, 두 축으로 구성됩니다.

Knowledge Hub (Utopia)

마이그레이션 과정에서 축적되는 전환 노하우, 컨벤션, 보안 정책을 Kiro가 이해할 수 있는 구조로 관리하는 중앙 지식 저장소입니다.

예시)

이 지식들은 시범 전환 과정에서 얻은 경험을 구조화한 것입니다. 한 서비스에서 세션 스토어를 Valkey로 전환하면서 겪은 시행착오, 발견한 패턴, 확립한 규칙이 Skill과 Steering으로 정리되어, 다음 서비스의 전환에서는 같은 시행착오를 반복하지 않습니다.

CLI Tool (lguctl)

Knowledge Hub의 지식을 개발자의 workspace에 세팅하고, 표준화된 작업 플로우를 실행하는 자동화 도구입니다.

개발자는 이 명령어들만 알면 됩니다. 내부적으로 CLI가 적절한 Custom Agent를 지정하여 kiro-cli 를 호출하고, 에이전트가 미리 정의된 컨텍스트와 워크플로우에 따라 작업을 수행합니다. 개발자는 어떤 Agent가 호출되는지, 어떤 컨텍스트가 주입되는지 알 필요가 없습니다.

CLI가 Custom Agent를 호출하는 방식

lguctl CLI는 내부적으로 kiro-cli chat –agent <agent-name> 명령을 호출하여 Kiro에게 작업을 지시합니다. 이때 단순히 프롬프트만 전달하는 것이 아니라, 해당 작업에 최적화된 Custom Agent를 지정하여 호출합니다. 각 Custom Agent는 프롬프트 파일(.md)과 설정 파일(.json) 쌍으로 정의됩니다. 설정 파일에는 에이전트가 읽어야 할 컨텍스트(resources)와 사용할 수 있는 도구(tools)가 선언되고, 프롬프트 파일에는 에이전트의 역할과 워크플로우가 기술됩니다.

예를 들어 Transform Agent는 프로젝트 정보(action_items.json), 전사 표준 Steering, Knowledge Search Power, Requirement Generator Power를 컨텍스트로 로드하고, “Action Item 분석 → 관련 Skill 검색(Knowledge Search Power) → 요구사항 생성(Requirement Generator Power) → 검증 계획 수립”이라는 워크플로우를 따릅니다.

Skill Creator Agent는 기존 Skill 카탈로그, skill-creator Skill, README를 컨텍스트로 로드하고, “기존 Skill 중복 확인 → Skill 구조 생성 → 품질 검증 → 카탈로그 등록”이라는 워크플로우를 따릅니다.

이렇게 에이전트마다 역할에 맞는 컨텍스트와 워크플로우를 미리 정의해두면, CLI가 프롬프트를 주입할 때 에이전트가 이미 필요한 지식과 절차를 갖춘 상태에서 작업을 시작합니다. 개발자가 “어떤 컨텍스트를 줘야 하지?”, “어떤 순서로 지시해야 하지?”를 고민할 필요가 없는 이유입니다.

실행 플로우: 개발자가 밟는 단계

Harness가 세팅된 환경에서 개발자는 Kiro를 두 가지 방식으로 활용합니다.

A. Knowledge Search — 언제든 지식 조회

전환 작업 전이나 작업 중 언제든, Kiro Chat에서 축적된 전환 노하우를 조회할 수 있습니다. 아래 2단계로 진행됩니다.

Step 1. Harness 환경 세팅 (최초 1회)

Knowledge Hub 세팅 + 프로젝트 정보 및 Action Item 다운로드를 한 번에 수행

lguctl project set --url <confluence-project-url>

이 명령 하나로 Knowledge Hub의 전사 공통 지식(Skills, Steering, Powers, Agents)을 workspace에 자동 구성하고, 프로젝트 고유의 설계 문서와 Action Item 목록(action_items.json)을 다운로드하여 workspace에 세팅합니다. 최초 1회만 수행하면 되며, 이미 세팅된 환경을 갱신하려면 --force 플래그를 사용할 수 있습니다.

Power 자동 세팅 원리
Skills, Steering, Agents는 workspace 내 .kiro/ 디렉토리에 파일을 복사하면 Kiro가 자동으로 인식합니다. 하지만 Power는 한 단계가 더 필요합니다. Kiro IDE에서 Power를 실제로 기동하려면 Kiro의 글로벌 레지스트리~/.kiro/powers/에 등록해야 합니다. Power 디렉토리 자체는 로컬 어디에든 존재할 수 있으며, 레지스트리가 해당 경로를 가리키고 있으면 동작합니다. lguctl project set을 실행하면 아래 3단계가 모두 수행됩니다. 1단계는 Power를 IDE에서 기동하기 위한 필수 조건은 아니지만, lguctl의 설계 원칙 — Utopia의 모든 설정(steering, skills, agents, project 정보)을 workspace의 .kiro/ 아래에 통합 관리 — 에 따라 Power 역시 동일하게 workspace에 배치됩니다.

> 참고: Power가 IDE에서 실제로 기동되려면 2~3단계의 레지스트리 등록이 필수입니다. 1단계의 workspace 복사는 Power 기동의 전제 조건이 아닙니다.

1.1 Power 디렉토리 복사
Knowledge Hub(Utopia)의 powers/ 디렉토리 아래에 있는 각 Power를 workspace의 .kiro/powers/로 복사합니다. Skills, Steering, Agents가 .kiro/skills/, .kiro/steering/, .kiro/agents/에 배치되는 것과 같은 맥락입니다. workspace 안에 모든 설정을 모아두면 프로젝트 단위로 관리하기 편리하고, lguctl project unset으로 한 번에 정리할 수 있습니다. 각 Power는 POWER.md(메타데이터 + 사용 가이드)를 포함하며, 필요에 따라 mcp.json(MCP 서버 설정), steering references등을 포함합니다.

{workspace}/.kiro/powers/
├── knowledge-search-power/
│   ├── POWER.md              ← name, keywords, description 정의
│   └── steering/             ← 지식 검색 워크플로우 가이드
├── requirement-generator-power/
│   ├── POWER.md
│   ├── steering/
│   └── assets/
├── db-query-transformer/
│   ├── POWER.md
│   ├── steering/
│   └── references/
└── detail-architecture-generator/
    ├── POWER.md
    ├── mcp.json              ← MCP 서버 엔드포인트 정의
    └── steering/

1.2 Kiro 글로벌 레지스트리 등록 (installed.json) — Power 기동에 필수
Kiro는 ~/.kiro/powers/installed.json 파일을 통해 설치된 Power 목록을 관리합니다. CLI는 이 파일에 각 Power를 등록하며, 두 가지 필드가 핵심 역할을 합니다.
– registryId: "user-added" — Kiro에게 이 Power가 공식 마켓플레이스가 아닌 사용자 추가(user-added) 레지스트리에서 온 것임을 알려줍니다. Kiro는 이 값을 보고 3단계의 user-added.json에서 Power의 실제 경로를 조회합니다.
– utopia_added: true — lguctl CLI가 자체적으로 추가한 마커입니다. Kiro가 사용하는 값이 아니라, lguctl project unset 실행 시 Harness가 추가한 Power만 선택적으로 제거하고 개발자가 직접 설치한 Power는 보존하기 위한 식별자입니다.

// ~/.kiro/powers/installed.json

{
  "version": "1.0.0",
  "installedPowers": [
    {
      "name": "knowledge-search-power",
      "registryId": "user-added",
      "Utopia_added": true
    },
    {
      "name": "db-query-transformer",
      "registryId": "user-added",
      "Utopia_added": true
    }
  ]
}

1.3 User-Added 레지스트리 등록 (user-added.json) — Power 기동에 필수
Kiro가 Power의 실제 위치를 찾을 수 있도록, ~/.kiro/powers/registries/user-added.json에 로컬 경로를 등록합니다.

// ~/.kiro/powers/registries/user-added.json

{
  "powers": [
    {
      "name": "knowledge-search-power",
      "description": "Custom power from /path/to/workspace/.kiro/powers/knowledge-search-power",
      "source": {
        "type": "local",
        "path": "/path/to/workspace/.kiro/powers/knowledge-search-power"
      },
      "Utopia_added": true
    }
  ]
}

source.type: "local"과 source.path를 통해 Kiro는 해당 Power의 POWER.md를 읽어 메타데이터(name, keywords, description)를 파악하고, mcp.json이 있으면 MCP 서버를 연결하며, steering이 있으면 워크플로우 가이드를 로드합니다. 이 3단계가 완료되면 Kiro는 Power를 완전히 인식하고, 사용자의 질의에서 Power의 keywords와 매칭되는 내용이 감지되면 자동으로 해당 Power를 활성화합니다. 개발자는 Power의 존재나 설정 방법을 알 필요 없이, 자연스럽게 Power가 제공하는 도구와 지식을 활용하게 됩니다. 개발자가 Kiro의 설정 체계를 몰라도, 이 명령 하나로 고급 설정이 완료된 환경에서 AI를 활용할 수 있습니다. 설정의 장벽이 사라집니다.

Step 2. Kiro Chat에서 지식 조회

Knowledge Hub가 세팅된 상태에서, Kiro Chat에 자연어로 질문하면 Harness에 세팅된 Skills, Steering, 설계 문서를 기반으로 관련 지식을 검색하여 답변합니다.

> "세션 스토어를 Valkey로 전환할 때 passwordless 인증은 어떻게 설정해야 하나요?"
>  Harness 지식 기반 답변:
   passwordless-auth-guide에 따르면, ElastiCache IAM 인증은
   SigV4 Presigned URL 방식으로 토큰을 생성하고,
   Lettuce RedisCredentialsProvider를 통해 연결 시마다
   토큰을 자동 갱신합니다.
   (session-store-valkey-migration skill 참조)

개발자가 전환 관련 궁금한 점을 자연어로 질문하면, 축적된 전환 노하우에서 답을 찾아줍니다. 별도의 문서를 뒤질 필요 없이, 작업 맥락 안에서 바로 지식에 접근할 수 있습니다. 이 조회는 작업 전이든 작업 중이든 언제든 반복할 수 있으며, Knowledge Hub에 Skill이 추가될수록 답변의 범위와 정확도가 함께 올라갑니다.

B. Spec 기반 전환 워크플로우 — Action Item 수행

실제 전환 작업은 아래 6단계로 진행됩니다.

Step 1. Harness 환경 세팅 (최초 1회)

A항목의 Step 1과 동일합니다. lguctl project set --url <confluence-project-url> 명령으로 Knowledge Hub 설정과 프로젝트 정보를 workspace에 세팅합니다. 이미 A항목에서 수행했다면 다시 실행할 필요가 없습니다.

Step 2. Action Item 선택 및 Requirement 작성

lguctl project create-requirement 명령을 실행하면 Step 1에서 다운로드된 action_items.json의 Action Item 목록이 인터랙티브 프롬프트로 표시됩니다. 개발자가 작업할 Action Item을 하나 선택하면(–title 플래그로 직접 지정도 가능), 시스템은 내부적으로 kiro-cli chat --agent transform-agent 명령으로 Transform Agent를 호출합니다. Transform Agent는 미리 정의된 컨텍스트(프로젝트 Action Item, Steering, Knowledge Search Power)를 로드한 상태에서 5단계 파이프라인으로 구조화된 요구사항 문서를 자동 생성합니다.

특히 Stage 3 구현 방법 생성은 requirement-generator Power와 knowledge-search Power의 연동으로 동작합니다. requirement-generator Power는 오케스트레이터 역할만 수행합니다. 구현 방법 섹션을 채울 때 직접 내용을 생성하지 않고, knowledge-search Power에게 질의를 위임합니다.

Skill Catalog: 지식 라우팅의 핵심
Knowledge Search Power는 steering/catalog.json에 등록된 Skill 카탈로그를 기반으로 라우팅합니다. 카탈로그에는 각 Skill의 도메인, 매칭 키워드, 제공 지식이 구조화되어 있습니다.

// catalog.json (발췌)

{
  "skills": [
    {
      "name": "session-store-valkey-migration",
      "domain": "Spring 기반 Java 앱의 인메모리 HttpSession → AWS ElastiCache Valkey 외부 세션 스토어 전환",
      "match_keywords": ["세션", "session", "Valkey", "Redis", "ElastiCache", "HttpSession", "세션 외부화", "Spring Session"],
      "provides": ["세션 분석 가이드", "Spring Session + Valkey 설정 패턴", "인프라 요구사항", "전환 사례"],
      "references": ["session-analysis-guide.md", "spring-session-valkey-config.md", "infrastructure-requirements.md"]
    },
    {
      "name": "file-storage-s3-migration",
      "domain": "로컬 파일시스템(WAS 내부) 또는 NAS 기반 파일 스토리지를 Amazon S3로 전환",
      "match_keywords": ["파일 스토리지", "S3 전환", "NAS", "파일 업로드", "파일 다운로드", "S3 버킷", "Presigned URL"],
      "provides": ["S3 버킷 설계 패턴", "S3 서비스 구현 패턴", "코드 전환 가이드", "LocalStack 테스트 환경"]
    }
  ]
}

질의에서 추출된 키워드가 카탈로그의 match_keywords와 2개 이상 일치하면 해당 Skill이 선택됩니다. 선택된 Skill의 SKILL.md(워크플로우, 가드레일)와 references/ 디렉토리의 상세 문서에서 구현 방안을 추출하여 requirements.md에 반영합니다.

Knowledge Hit vs Miss — 출력 차이
매칭 Skill이 존재하는 경우, 검증된 전환 패턴이 그대로 요구사항에 반영됩니다.

예시)

# 구현 방법
> Knowledge: knowledge-search (session-store-valkey-migration 기반)
1. Spring Session + Valkey 의존성 추가 (spring-session-data-redis)
2. RedisConnectionFactory를 LettuceConnectionFactory로 구성
3. @EnableRedisHttpSession 어노테이션 적용
4. 환경별 설정 파일 분리 (local: 무인증, dev/prod: IAM 인증)
5. Locale 역직렬화 폴백 처리 (RedisSessionLocaleResolver 구현)
### 인프라 요청 사항 (Human 영역)
- ElastiCache Valkey 클러스터 생성 (인프라팀 요청)
- IAM 인증 기반 접속 정책 설정

매칭 Skill이 없는 경우, LLM이 대안을 제안하되 [Proposal] prefix로 명확히 구분합니다.

예시)

# 구현 방법
[Proposal] 기존 무한루프(while(true)) 기반 폴링을 @Scheduled(fixedDelay=1000) 어노테이션으로 전환한다.
[Proposal] 기존 상속 구조(SMSManager extends SMSConfig)를 독립 @Service 컴포넌트로 재구성한다.

이 구분이 중요한 이유는, >>Knowledge표기된 내용은 이미 다른 서비스에서 검증된 패턴이므로 높은 신뢰도로 적용할 수 있고, [Proposal] 표기된 내용은 개발자가 Step 3(리뷰)에서 더 신중하게 검토해야 한다는 신호를 주기 때문입니다.

가드레일: 없는 지식을 만들어내지 않는다
이 메커니즘의 핵심 가드레일은 등록된 “knowledge에 없는 내용은 절대 생성하지 않는다” 는 원칙입니다. Knowledge Search Power가 매칭 Skill을 찾지 못하면 “없다”고만 반환하고, LLM이 임의로 지식을 생성하여 >> Knowledge로 위장하는 것을 금지합니다. 대신 requirement-generator Power가 [Proposal]로 명시적으로 구분된 LLM 제안을 생성합니다. 이 설계 덕분에 개발자는 requirements.md를 리뷰할 때, >> Knowledge 섹션은 축적된 조직 지식임을 신뢰할 수 있고, [Proposal] 섹션은 추가 검증이 필요한 제안임을 즉시 판별할 수 있습니다.

4단계 검증 계획은 requirement-generator Power가 build-and-test Skill을 호출하여 생성합니다. 서비스별 빌드 커맨드, 로컬 인프라 기동 절차, 스모크 테스트 방법이 요구사항에 자동으로 포함되므로, 이후 Kiro가 태스크를 수행할 때 검증 단계를 빠뜨리지 않습니다.
개발자가 프롬프트를 고민할 필요가 없습니다. 축적된 전환 노하우가 반영된 요구사항이 자동으로 만들어집니다. 프롬프트 품질의 격차가 사라집니다.

Step 3. Requirements 리뷰 (Human-in-the-Loop)

.kiro/specs/act-002-session-store-migration/
└── requirements.md    ← 개발자가 리뷰 및 수정

자동 생성된 requirements.md를 개발자가 직접 리뷰합니다.
– 자동 생성된 요구사항의 정확성 확인
– 서비스 고유의 비즈니스 컨텍스트 반영
– 누락된 항목 보완
AI가 만든 결과를 무조건 수용하는 것이 아니라, 개발자가 검토하고 보완하는 Human-in-the-Loop 과정입니다. AI의 속도와 사람의 판단력을 결합하는 지점입니다.

Step 4. Design & Task 생성 → 전환 작업 수행

개발자가 Kiro Spec 기능을 사용하여 리뷰가 완료된 requirements.md를 기반으로 설계 문서(design.md)와 구현 태스크(tasks.md)를 순차적으로 생성합니다. Kiro Spec은 requirements → design → tasks 순서로 문서를 생성하며, 각 단계마다 개발자가 리뷰하고 Accept/Reject를 결정하는 구조입니다.

.kiro/specs/act-002-session-store-migration/
├── requirements.md    ← Step 2~3에서 생성 및 리뷰 완료
├── design.md          ← Kiro가 requirements 기반으로 설계 문서 생성
└── tasks.md           ← Kiro가 design 기반으로 구현 태스크 목록 생성

Kiro는 Harness에 세팅된 Skills, Powers, Steering을 활용하여 전사 표준 컨벤션과 보안 정책이 반영된 코드를 생성합니다. 예를 들어 세션 스토어를 Valkey로 전환하는 작업에서

– Skill session-store-valkey-migration 이 전환 패턴과 구현 가이드를 제공
– Steering passwordless-auth-guide 이 IAM 기반 인증 정책을 강제
– Steering properties-convention이 환경별 설정 분리 규칙을 적용
개발자가 이 규칙들을 일일이 기억하지 않아도, Harness가 자동으로 반영합니다.

Steering의 실제 구조 — passwordless-auth-guide 예시
Steering은 Kiro가 코드를 생성할 때 항상 자동으로 로드되는 정책 문서입니다. inclusion: auto 설정으로 관련 키워드가 감지되면 별도 지시 없이 컨텍스트에 주입됩니다.

---
inclusion: auto
name: passwordless-auth-guide
description: DB 연동, JDBC 설정, Aurora MySQL 접속, ElastiCache/Valkey/Redis 연결, IAM 인증, passwordless 인증 등 데이터베이스 또는 캐시 접근/연동 작업 시 자동 로드.
---
# Passwordless 인증 가이드
## 개요
운영 환경에서는 DB, 캐시 모두 패스워드 없이 IAM 토큰으로 인증하는 것이 원칙이다.
로컬 환경에서는 일반 ID/PW 인증 또는 무인증을 사용한다.
## 1. Aurora MySQL — IAM 인증
- AWS JDBC Wrapper(software.amazon.jdbc.Driver)가 IAM 토큰을 자동 생성
- jdbc:aws-wrapper:mysql:// 프로토콜 + wrapperPlugins=iam 파라미터
- JDBC_PASSWORD는 비워둔다 (드라이버가 토큰 자동 생성)
## 2. ElastiCache (Valkey/Redis) — IAM 인증
- SigV4 Presigned URL 방식으로 토큰 생성
- Lettuce RedisCredentialsProvider를 통해 연결 시마다 토큰 자동 갱신
- 토큰 유효기간: 15분 (TOKEN_EXPIRY_SECONDS = 900)
## 환경별 설정
| 환경 | IAM_AUTH | SSL | 인증 방식 |
|------|----------|-----|-----------|
| 로컬 | false    | false | 인증 없음 |
| 개발 | true     | true  | IAM 토큰 + TLS |
| 운영 | true     | true  | IAM 토큰 + TLS |

Skill + Steering 연동이 만드는 효과

Kiro가 세션 스토어 전환 코드를 생성할 때 실제로 일어나는 일:

결과적으로 Kiro가 생성하는 코드에는:
– Skill이 제공하는 전환 패턴 (Spring Session 설정, Lettuce 연결 팩토리, 직렬화 처리)
– Steering이 강제하는 보안 정책 (IAM 토큰 인증, 패스워드 하드코딩 금지)
– Steering이 강제하는 컨벤션 (환경별 properties 분리, 주입 우선순위)
이 세 가지가 자동으로 반영됩니다. 개발자가 “IAM 인증을 적용해야 한다”거나 “properties는 이 경로에 넣어야 한다”고 일일이 지시하지 않아도, Harness가 조직의 표준을 코드에 녹여냅니다.

Step 5. 테스트 및 검증

코드 전환이 완료되면, 변환된 코드가 정상적으로 동작하는지 검증하는 단계입니다. Harness는 이 과정에서 두 가지 도구를 자동으로 활용합니다.
빌드 및 통합 검증 — build-and-test Skill
전환된 서비스가 실제 인프라 환경에서 정상 동작하는지 먼저 확인합니다. 특히 세션 스토어 전환, S3 마이그레이션, DB 연결 방식 변경 같은 인프라 설정이 수반되는 작업에서는 로컬 환경에서의 통합 검증이 필수입니다.
build-and-test Skill은 서비스별 빌드 도구와 환경을 파악한 뒤, 로컬 빌드 → 앱과 인프라 기동(Docker Compose로 MySQL, LocalStack, Valkey 등) → 스모크 테스트까지 동일한 환경에서 일관된 절차로 검증을 수행합니다.

이 검증 절차는 Step 2의 요구사항 생성 시점에 requirements.md에도 포함됩니다. requirement-generator Power가 build-and-test Skill을 호출하여 서비스별 빌드 커맨드, 인프라 기동 절차, 스모크 테스트 방법을 요구사항에 자동으로 반영하기 때문입니다. 덕분에 Kiro가 태스크를 수행할 때 검증 단계를 빠뜨리지 않고, 개발자가 별도로 검증 절차를 기억하거나 지시할 필요가 없습니다.
유닛 테스트 자동 생성 — unit-test-generator Power
빌드 및 통합 검증이 통과되면, unit-test-generator Power가 변환된 코드에 대한 유닛 테스트를 자동으로 생성합니다. 이 Power는 현재 feature 브랜치와 main 브랜치의 merge-base를 비교하여 전환 작업에서 변경된 코드를 식별하고, 파일 → 클래스 → 메서드 단위로 분해하여 테스트코드를 자동 생성합니다.

워크플로우가 중단되더라도 태스크 파일이 남아 있으므로, 다시 실행하면 미완료 항목부터 자동으로 재개됩니다. 개발자가 테스트 코드를 직접 작성할 필요 없이, 전환된 코드의 동작을 검증하는 테스트가 자동으로 만들어집니다. 테스트가 실패하면 Power가 원인을 분석하고 자동으로 수정을 시도하므로, 개발자는 최종 결과만 확인하면 됩니다.

Step 6. 전환 경험 지식 자산화

전환 작업이 완료되면, 수행 결과를 조직 지식으로 남기는 두 가지 자산화가 이루어집니다.
이행 작업 문서화 — confluence-doc-generator Skill
각 Action Item의 전환 작업이 끝나면, confluence-doc-generator Skill이 수행한 작업 내용을 Confluence 표준 템플릿에 맞춰 자동으로 문서화합니다. 개요, 기존 구현 방식, 주요 변경 사항, 핵심 코드 변경 내역, 인프라 요구사항, 테스트 결과, 잔여 Action Item까지 — 표준화된 구조로 정리된 기술 적용 보고서가 Confluence에 자동 생성됩니다. 이 문서화 단계는 개발자가 별도로 기억하거나 지시할 필요가 없습니다. Step 2에서 requirement-generator Power가 요구사항을 생성할 때, 마지막 섹션에 confluence-doc-generator Skill 호출 지시를 자동으로 포함하기 때문입니다. Kiro Spec이 이 요구사항을 기반으로 태스크를 생성하면, 마지막 태스크가 항상 “Confluence 문서화”가 됩니다.
개발자가 작업 결과를 정리하는 데 시간을 쓰지 않아도, 표준화된 문서가 자동으로 남습니다. 문서화 누락이 사라지고, 프로젝트 전체의 전환 이력이 일관된 형식으로 축적됩니다.

전환 패턴 Skill 자산화 — create-skill

# confluence-doc-generator가 생성한 Confluence 페이지 URL을 입력으로 사용
lguctl project create-skill --url <confluence-doc-generator가 반환한 URL>

앞 단계에서 confluence-doc-generator Skill이 Confluence에 업로드한 이행 문서의 URL을 그대로 create-skill의 입력으로 사용합니다. 이행 문서 생성 → Skill 자산화가 하나의 흐름으로 이어지는 구조입니다. Confluence에 문서화된 전환 경험을 한 단계 더 나아가, 재사용 가능한 Skill로 변환합니다. 시스템은 내부적으로 kiro-cli chat --agent skill-creator-agent 명령으로 Skill Creator Agent를 호출합니다. Skill Creator Agent는 기존 Skill 카탈로그와 skill-creator Skill을 컨텍스트로 로드한 상태에서, 전달받은 Confluence 페이지의 이행 문서를 분석하고, 기존 Skill과의 중복을 확인한 뒤, 표준 Skill 구조로 자동 생성하여 Knowledge Hub에 등록합니다.

이렇게 자산화된 Skill은 동일한 유형의 전환 작업을 수행하는 다른 개발자, 다른 프로젝트에서 즉시 재사용됩니다. 전환을 할수록 지식이 쌓이고, 다음 전환은 더 빨라지는 선순환 구조입니다.

Harness가 만드는 차이

Harness Engineering의 핵심 가치를 정리하면 다음과 같습니다.

설정 격차 해소

품질 격차 해소

지식의 선순환

전환을 반복할수록 Knowledge Hub의 지식이 풍부해지고, 새로운 전환 작업의 품질과 속도가 함께 올라갑니다.

기대 효과

저희는 약 100개의 서비스에 대한 클라우드 마이그레이션을 진행하고 있습니다. 성숙도가 다른 수십 개 개발사의 개발자들이 동시에 전환 작업에 참여합니다. Harness Engineering을 통해 기대하는 임팩트는 다음과 같습니다.

• 온보딩 시간 단축 — 새로운 개발사가 프로젝트에 투입될 때, AI 환경 설정과 작업 프로세스 학습에 소요되는 시간을 CLI 명령어 수준으로 단축합니다. 복잡한 설정 가이드를 읽고 따라하는 대신, lguctl project set 한 줄이면 전사 표준이 적용된 환경이 준비됩니다.
• 전환 작업 가속화 — 각 Action Item의 요구사항 작성, 설계, 구현 과정에서 축적된 전환 노하우가 자동으로 반영됩니다. 이전 서비스에서 검증된 패턴을 다음 서비스에 즉시 적용할 수 있어, 서비스를 전환할수록 속도가 빨라집니다.
• 품질 하한선 보장 — 개발자의 AI 활용 성숙도와 무관하게, Steering이 전사 표준 컨벤션과 보안 정책을 강제하고, Skill이 검증된 구현 패턴을 제공합니다. unit-test-generator Power가 변환된 코드에 대한 유닛 테스트를 자동 생성하고, build-and-test Skill이 로컬 환경에서의 통합 검증을 수행하므로, 코드 전환 후 검증이 누락되는 일이 없습니다. 결과물의 최소 품질이 보장되므로, 리뷰와 재작업 비용이 줄어듭니다.
• 조직 지식의 복리 효과 — 전환 경험이 개인의 암묵지로 남지 않습니다. 각 Action Item 완료 시 confluence-doc-generator Skill이 표준화된 이행 문서를 Confluence에 자동 생성하고, create-skill이 전환 패턴을 Skill로 자산화하여 조직 전체가 재사용합니다. 100개 서비스를 전환하는 동안 축적되는 문서와 Skill은 이후 유사한 마이그레이션 프로젝트에서도 그대로 활용할 수 있습니다.

마치며

Harness Engineering은 결국 하나의 질문에서 출발했습니다.

 “AI 도구를 도입했는데, 어떻게 하면 모든 개발자가 동일한 수준으로 활용할 수 있을까?”

저희의 답은 설정을 자동화하고, 플로우를 패턴화하고, 지식을 자산화하는 것이었습니다. 개발자에게 더 좋은 프롬프트를 쓰라고 교육하는 대신, 시스템이 좋은 프롬프트를 만들어주는 구조를 설계했습니다. 개발자에게 설정을 공부하라고 요구하는 대신, CLI 한 줄로 최적의 설정이 적용되는 환경을 제공했습니다. AI 도구의 잠재력은 도구 자체가 아니라, 그 도구를 조직에 어떻게 녹이느냐에 달려 있습니다. Harness Engineering이 그 방법 중 하나가 될 수 있기를 바랍니다. Knowledge Hub의 지식을 개발자의 workspace에 세팅하고, 표준화된 작업 플로우를 실행하는 자동화 도구입니다.