Build a repeatable PHP-to-Java migration engine with Kiro

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Kiro와 AWS Transform에서 공유하는 스킬, 기계적 탐색 스캐너, PHP 원본과 Java 이식본의 동작 동등성 검증을 결합해 PHP-to-Java 마이그레이션을 반복 가능한 과정으로 만드는 방법을 소개한다.

📌 핵심 요약

• PHP-to-Java 전환은 타입 안전성, 라이브러리 지원, 확장 예측 가능성을 높일 수 있지만, Laravel·Symfony·Doctrine 코드에 숨은 업무 규칙 때문에 Java 코드가 컴파일되어도 원본과 다르게 동작할 수 있다. 제안된 방법론은 PHP 원본을 명세로 삼고 동작 동등성 검증 하네스를 완료 판정 기준으로 사용한다.
• php-to-java-migration과 php-model-discovery 스킬은 공통 방법론을 파일로 보관한다. Kiro는 명시적 승인 단계를 거쳐 애플리케이션 하나씩 대화형으로 진행하고, AWS Transform은 같은 스킬을 사용해 여러 애플리케이션을 병렬 작업으로 처리한다.
• discover-models.php는 PHP 8.0 이상에서 대상 코드를 실행하거나 의존성을 설치하지 않고 소스 토큰을 분석한다. Eloquent 상속 관계, Doctrine 엔터티 속성, ORM XML 매핑을 탐색해 models[]와 항목별 flags[]를 포함한 JSON 매니페스트를 만들며, 모호한 내용은 사람이 검토하도록 표시한다.
• 준비 단계인 Phase 0 이후 Phase 1~8을 진행한다. Java 작성 전에 검증 하네스를 구축하고 의도적으로 주입한 오류를 탐지하는지 확인한 뒤, RULEBOOK.md와 GAP_INVENTORY.md를 정비하고 Spring Boot 골격, 데이터 모델, I/O 계층, 업무 로직을 변환한다. 불일치는 규칙서를 수정해 재생성하거나 승인된 변경으로 기록한다.
• laravel-eloquent-sample은 전체 37개 모델 중 Book·Chapter·Page·User 4개만 Spring Boot 3.4.1, Java 21, Maven, 인메모리 H2 환경으로 이식한 읽기 전용 예제다. 이 예제에는 동작 동등성 검증 하네스가 구축되지 않았으며, 명세도 이를 가장 큰 공백으로 명시한다.

🧩 주요 포인트

1. 컴파일 성공과 동작 일치는 별개 → PHP 원본을 기준으로 삼고, 정상 동작과 의도적 오류 모두를 판별하는 검증 하네스로 이식 결과의 신뢰성을 판단한다.
2. Kiro와 AWS Transform이 스킬 파일을 공유 → 한 실행에서 보완한 규칙을 다른 프로젝트와 실행 방식에도 재사용할 수 있어 방법론 개선이 누적된다.
3. 스캐너의 flags[]와 예제의 4/37 모델·검증 하네스 부재가 한계를 드러냄 → 자동 변환 결과를 평가할 때 미해결 모호성과 실제 검증 범위를 함께 확인해야 한다.

🧠 상세 정리

1. Java 전환의 이점과 동작 보존의 어려움

글은 오래 운영한 PHP 애플리케이션을 Java로 옮기면 더 강한 타입 안전성, 폭넓은 라이브러리 지원, 더 예측 가능한 확장을 얻을 수 있다는 전제에서 출발한다. 그러나 Laravel, Symfony, Doctrine으로 축적된 코드에는 Eloquent 트레이트나 XML 매핑 파일처럼 쉽게 드러나지 않는 위치에도 업무 규칙이 들어 있어, 구조가 비슷하고 컴파일까지 성공한 Java 이식본도 다른 결과를 낼 수 있다. 이를 해결하기 위해 Kiro를 활용한 공통 방법론, 기계적 탐색 스캐너, 8단계 워크플로를 재사용 가능한 엔진으로 구성하고 PHP 원본 자체를 명세로 취급한다. Kiro는 코드베이스와 함께 여러 단계의 엔지니어링 작업을 수행하는 AI 에이전트를 제공하는 IDE이며, 이 방식에서는 검증 하네스가 동작 동등성을 확인해야 이식이 올바르다고 판정한다. 시작하려면 PHP와 관련 프레임워크에 대한 이해, Skills와 Steering 파일을 사용할 수 있는 Kiro 작업 공간, 스캐너용 PHP 8.0 이상, 생성 프로젝트용 Java 21과 Maven이 필요하며 Java 지식은 결과 검토에 도움이 된다.

2. 공유 스킬을 실행하는 Kiro와 AWS Transform

마이그레이션 지식은 특정 도구 안에만 두지 않고, 버전 관리되는 Markdown 기능 패키지인 php-to-java-migration과 php-model-discovery 스킬 파일에 담는다. Kiro에서는 저장소 루트를 작업 공간으로 열고 PHP 애플리케이션 마이그레이션을 요청하면 스킬이 자동으로 활성화되며, 개발자는 탐색 매니페스트를 검토하고 규칙서를 승인하는 등 각 단계의 명시적 승인 절차에 참여한다. AWS Transform은 대규모 마이그레이션과 현대화를 위한 AWS의 에이전트형 AI 서비스로 소개되며, Kiro와의 네이티브 통합을 통해 같은 스킬 파일과 검증 원칙을 사용한다. 글은 처음 접하는 프레임워크나 애플리케이션 하나를 직접 이해하고 생성 Java와 테스트를 확인할 때 Kiro가 적합하고, 여러 애플리케이션을 병렬 작업으로 처리할 때 AWS Transform이 적합하다고 설명한다. 두 경로가 같은 파일을 읽으므로 Kiro에서 수정한 규칙이 다음 AWS Transform 실행에 반영되고, 반대 방향의 개선도 공유되는 피드백 구조가 성립한다.

3. 공통 방법론과 프로젝트별 산출물의 분리

작업 공간의 중심 원칙은 하나의 공통 방법론을 여러 프로젝트가 함께 사용하도록 구성하는 것이다. 저장소를 복제한 뒤 .kiro/가 있는 루트 폴더를 Kiro에서 열면 스킬과 Steering이 자동으로 로드되며, 전역 .kiro/ 계층에는 탐색용 php-model-discovery, 마이그레이션용 php-to-java-migration, core-workflow.md Steering 파일이 놓인다. 그 아래의 각 프로젝트 폴더는 자체 PHP 소스와 Java 출력, .kiro/specs/ 아래의 프로젝트별 명세 하위 폴더를 보유해 공통 지식과 개별 애플리케이션 자료를 구분한다. 이 구성에서는 프로젝트마다 방법론을 따로 수정할 필요 없이 공유 계층을 한 번 개선하면 각 프로젝트가 그 개선을 이어받을 수 있다. Kiro와 AWS Transform은 이 동일한 구조와 동등성 우선 파이프라인을 서로 다른 실행 방식으로 구동하며, PHP 소스를 검증된 Spring Boot Java로 전환하는 것을 목표로 한다.

4. 변환보다 먼저 수행하는 기계적 탐색

탐색 단계의 핵심 규칙은 스캐너가 실행되기 전에 모델이나 엔터티 파일을 읽고 추측하거나 수작업으로 번역하지 않는 것이다. discover-models.php는 단일 파일로 된 의존성 없는 PHP 명령줄 도구이며, 대상 애플리케이션을 실행하지 않고 소스 텍스트를 토큰으로 읽으므로 대상의 의존성이 설치되지 않은 상태에서도 분석할 수 있다. 매번 Illuminate\Database\Eloquent\Model까지의 클래스 상속 관계를 추적하는 Eloquent 탐색, #[ORM\Entity]를 확인하는 Doctrine 속성 탐지, 외부 *.orm.xml 파일 분석이라는 세 전략을 수행한다. 결과는 필드, 형 변환, 관계, 가시성 규칙을 담는 models[] 배열과 각 항목의 flags[] 배열을 포함한 하나의 JSON 매니페스트로 모인다. 예를 들어 $fillable 목록이 런타임 표현식으로 구성되어 정적으로 확정하기 어렵다면 값을 추측하지 않고 자연어 설명으로 표시하며, 이 표시들이 사람이 해결해야 할 검토 대기 항목이 된다.

5. Phase 0~3에서 검증 기준과 변환 규칙 확립

워크플로는 준비 단계인 Phase 0과 뒤이은 Phase 1~8로 구성되며, 사람의 전문적 판단은 주로 Phase 0~3에 집중된다. Phase 0은 스캐너를 실행해 모델 매니페스트와 전체 목록을 만들고 전환 방식을 선택하며, Phase 1은 Java를 작성하기 전에 PHP 원본과 Java 이식본에 요청·응답 쌍을 재실행할 동작 동등성 검증 하네스를 구축한다. 이 하네스는 정상 PHP에서 통과하는 것뿐 아니라 의도적으로 동작을 깨뜨렸을 때 실패해야 하며, 주입한 오류를 놓치는 하네스는 신뢰하지 않는다는 기준을 적용한다. Phase 2에서는 변환 규칙을 담는 RULEBOOK.md와 미해결 공백을 정리하는 GAP_INVENTORY.md의 초기 내용을 마련해 이후 변환의 기준을 세운다. Phase 3에서는 대표 파일들을 대상으로 규칙서를 강하게 시험하고 보완한 뒤 애플리케이션 전체에 적용하므로, 본격적인 코드 생성 전에 판단 기준과 예외를 구체화하는 흐름이다.

6. Phase 4~8의 변환 반복과 완료 판정

Phase 4~8은 검증 하네스의 판정을 받으며 대부분 자율적으로 반복 실행하는 구간으로 설명된다. Phase 4에서는 컴파일 가능한 Spring Boot 프로젝트 골격을 만들고, Phase 5에서는 탐색 매니페스트를 기준으로 JPA 엔터티와 스키마 기준선을 생성한다. Phase 6은 I/O 계층을 옮기는 단계로 라우트를 컨트롤러로, 미들웨어를 필터로, 검증 규칙을 애너테이션이 붙은 데이터 전송 객체로 바꾸며 보안과 템플릿도 응답하도록 구성한다. Phase 7에서는 업무 로직을 묶음 단위로 변환하고 테스트를 통과시키며, Phase 8에서는 검증 하네스로 동등성을 입증한 보고서와 전환 점검 항목을 마련해 실제 전환으로 이어간다. 전체 반복의 원칙은 PHP가 명세라는 점과 개별 Java 코드를 수작업으로 고치기보다 규칙서를 수정하고 재생성한다는 점이며, 불일치는 검증 기준을 만족하도록 해결하거나 각각 승인된 변경으로 기록해야 한다.

7. Eloquent 예제의 추적 가능한 매핑과 검증 공백

laravel-eloquent-sample은 오픈소스 Laravel 애플리케이션의 읽기 전용 일부를 대상으로 Book, Chapter, Page, User 모델을 Spring Boot 3.4.1과 Java 21, Maven, 인메모리 H2 데이터베이스 환경으로 옮긴 제한된 예제다. 매핑은 매니페스트에서 추적할 수 있도록 기계적으로 이루어지며 PHP 네임스페이스는 Java 패키지로, Eloquent 모델은 JPA @Entity로, hasMany와 belongsTo 관계는 각각 @OneToMany와 @ManyToOne으로, 쿼리 스코프는 Spring Data 저장소 메서드로 변환된다. 직렬화에서도 Page의 $hidden 목록에 기록된 html, markdown, text에는 @JsonIgnore를 붙이고, Book의 description에는 의도적으로 붙이지 않아 모델별 노출 규칙을 구분한다. 다만 전체 37개 모델 중 4개만 이식했으며, 이 범위에는 동작 동등성 검증 하네스가 만들어지지 않았다는 중요한 한계가 있다. 예제 명세는 이를 가장 큰 공백이라고 명시하므로, 글이 제시하는 검증 중심 방법론과 해당 예제가 실제로 입증한 범위를 구분해야 한다.

8. 실행 시작과 프레임워크 확장 방식

시작 절차는 공개된 PHP-to-Java 마이그레이션 예제 저장소를 복제하고 .kiro/를 포함하는 루트를 Kiro 작업 공간으로 여는 것이며, 글은 스캐너용 PHP 8.0 이상과 생성 프로젝트용 Java 21 및 Maven을 실행 요건으로 제시한다. 이후 프로젝트의 source-php/ 폴더에 PHP 소스를 가져오며, README에는 동일한 기준 상태를 재현할 수 있도록 동등성 검증에 사용하는 정확한 업스트림 커밋이 고정되어 있다. Kiro에 마이그레이션을 요청하면 php-to-java-migration 스킬이 활성화되어 스캐너를 먼저 실행하고 .kiro/specs/ 아래에 새 명세를 만든 뒤 승인 단계를 안내한다. 여러 애플리케이션을 에이전트 방식으로 처리하려면 AWS Transform에 같은 스킬 파일을 제공해 동일한 방법론을 실행하도록 한다. 방법론은 Laravel, Symfony, CodeIgniter, 일반 PHP를 자동 감지하며, 새로운 프레임워크를 지원할 때는 감지 항목과 references/<framework>-to-spring.md 가이드를 추가하는 확장 방식을 제시한다.

🧾 핵심 주장 / 시사점

• 검증 하네스 자체에 오류 탐지 능력을 요구한다는 점에서, 이 방법론의 신뢰 기반은 코드 생성 능력뿐 아니라 완료 판정 기준의 정확성에도 있다.
• 개별 출력물을 수작업으로 수정하는 대신 공유 규칙서를 고치고 재생성하면, 한 프로젝트에서 발견한 문제를 이후 프로젝트의 변환 품질 개선으로 연결할 수 있다.
• 스캐너가 모호성을 드러내고 예제가 검증 부재를 명시하는 방식은 자동화의 범위를 평가하는 데 도움이 되지만, 예제 실행만으로 전체 애플리케이션의 동작 동등성이 입증되는 것은 아니다.

✅ 액션 아이템

• PHP 원본을 기준으로 검증 하네스가 정상 동작을 통과시키고 의도적 오류를 탐지하는지 확인한다.
• Kiro와 AWS Transform에서 재사용할 수정 사항을 공유 스킬과 RULEBOOK.md에 반영한다.
• laravel-eloquent-sample의 4/37 모델 범위와 검증 하네스 부재를 이식 결과 평가에 반영한다.

❓ 열린 질문

• PHP 원본과 Java 이식본을 비교하는 검증 하네스는 어떤 동작 범위까지 다뤄야 하는가?
• 스캐너의 flags[]에 남은 모호성 중 Java 변환 전에 해결해야 할 항목은 무엇인가?
• laravel-eloquent-sample의 4/37 모델 범위를 확대할 때 검증 하네스 부재를 어떻게 해소할 것인가?