Flutter Agent Skill을 평가로 발전시키기 — 한 번에 모든 항목 통과하지 못한 개선 기록

서론

지난 글에서는 제가 이상적으로 생각하는 Flutter 앱의 설계 방식을 Agent Skill로 정리하여 Reading Shelf라는 샘플과 함께 공개했습니다. Riverpod으로 상태를 관리하고, Repository로 통신과의 경계를 만들며, Freezed・다국어 지원・타입 지정 라우트를 조합하는 방향입니다.

공개 후, Skill 유무에 따라 같은 작업을 실행해 보니, Skill이 있어도 규약 적합도는 11개 항목 중 3개였습니다. 단순히 방식을 문서로 만든 것만으로는 구현 시의 판단에 충분한 도움을 주지 못했습니다.

그래서 평가 결과로부터 지시를 수정하고, 동일한 작업으로 재평가하는 작업을 계속했습니다. 이 글에서 'Skill을 수정하여 재평가하는 각 단계'를 Iteration이라고 부릅니다. Iteration 8에서는 한 번 모든 항목을 통과했지만, 같은 Skill이라도 다시 실행하니 놓치는 부분이 있었습니다. 그 원인을 반영한 Iteration 9에서는 세 번 모두 기능 요구사항・규약・기계적 체크를 모두 통과했습니다.

이 글에서는 2026년 9월 28일부터 30일까지 진행된 평가를 바탕으로, 어느 부분에서 지시가 제대로 전달되지 않았는지, 그리고 무엇을 변경했는지를 소개합니다. 특히 중요했던 점은 규약의 적용 조건을 구체화하는 것, 동작과 규약을 분리하여 평가하는 것, 모든 항목을 통과한 버전이라도 반복적으로 시도하는 것이었습니다.

무엇을 평가했나

평가 대상은 기존 앱에 대한 다음 3가지 케이스입니다.

두 조건 모두 동일한 초기 프로젝트, SDK, 초기 lockfile을 전달합니다. Skill이 있는 경우에만 SKILL.md

・참조 문서 및 실행 가능한 샘플을 포함하는 스냅샷을 명시적으로 전달했습니다. 즉, 측정하고 있는 것은 이 일체를 제공했을 때의 구현에 미치는 영향입니다. Skill이 자동으로 적절하게 선택되는지는 측정하지 않았습니다.

평가는 다음 3가지로 나누었습니다.

기능 요구사항과 규약을 나눈 이유는, 아무리 마음에 드는 구성이라 하더라도 요청된 동작이 망가졌다면 성공이라고 할 수 없기 때문입니다. 또한, 기계적 체크의 성공만으로는 테스트되지 않은 동작까지 보장할 수 없습니다. 이 구분이 이후 개선에 도움이 되었습니다.

평가의 자세한 내용은 평가 절차와 케이스・채점 기준에 있습니다. 아래 링크도 기사 작성 시점의 커밋에 고정했습니다.

개선의 전체적인 모습

주요 평가 단계의 Skill이 있는 결과들을 정리했습니다. 그래프는 기능 요구사항과 규약 각각의 달성률입니다.

막대의 길이는 달성률이며, 오른쪽 숫자는 통과 항목 수/평가 항목 수입니다. 반복 평가는 3회분을 집계했기 때문에 분모가 다릅니다.

CLI는 Iteration 1부터 2까지 바뀌었고, Iteration 4부터는 독립적인 재생성 검사를 추가했습니다. 따라서 이 표와 그래프는 개선 과정을 보여주는 것이며, 동일 조건에서 Skill만 바꾼 효과를 측정한 것은 아닙니다. 수치는 첫 기록과 본문에서 참조하는 각 회차의 평가 보고서를 기반으로 합니다.

Flutter용 Skill에는 공식의 태스크별 Skill 모음집이나 개발 전반을 다루는 커뮤니티의 Skill 모음집도 있습니다. 이번 Skill의 위치를 알 수 있도록, 2026년 10월 1일에 확인한 공개 문서를 바탕으로 대상 범위와 방침을 간단히 정리합니다.

검증 처리에도 차이가 있습니다. 공식 설계 Skill은 ViewModel・Repository의 단위 테스트와 수정・재실행을 절차에 포함합니다. flutter-skills는 출력이나 Skill 선택의 평가와, 분석・실행 테스트를 수반하는 결과를 공개하고 있습니다. building-flutter-apps는 lint・테스트 외에도 플러그인 도입 시의 hooks에서도 규약을 검사합니다. 이번 Skill은, 기존 앱 3케이스에서 기능 요구사항・규약・기계적 체크를 나누어 반복 평가했습니다.

공식 설계 방침에 대해서는 Architecture Best Practices Skill을, 커뮤니티 버전의 평가 방법에 대해서는 공개 벤치마크를 참조했습니다. 평가 대상이나 실행 조건이 다르기 때문에, 각 리포지토리의 점수를 나열한 성능 비교는 하지 않았습니다.

Riverpod을 축으로 설계를 맞추는 Skill은 다른 것도 있습니다. 위의 building-flutter-apps가 채택 기술이 특히 가깝고, zakariaf/Flutter-Skills에도 Riverpod 3.x를 중심으로 다루는 state-management-riverpod이 있습니다. 이번 Skill에서는, Hooks에 의한 로컬 상태 관리나 OpenAPI 생성 클라이언트의 재현성까지 포함하는 구체적인 규약과, 그것을 기존 앱의 변경으로 반복 평가한 과정을 소개합니다.

제 자신의 Skill도, 책임 분리(責務分離)나 Repository의 생각은 공식 Skill을 토대로 하고 있습니다. 그 위에, 화면 상태는 Riverpod에 두고, 다른 ViewModel을 필수로 하지 않는 등 자신이 채택하고 싶은 구성을 명시했습니다. 이번에 확실히 하고 싶었던 것은, 이 구체적인 방침이 기존 앱의 변경에서도 구현에 반영되는지, 그리고 요구된 동작을 유지할 수 있는지 하는 점이었습니다.

'사용하는 것'에서 '언제, 어디에 적용할지'로

최초 Skill에는, Freezed나 context.l, 타입형 라우트를 사용할 방침을 적어 놓았습니다. 그래도 작은 기존 앱을 변경하는 태스크에서는 충분히 채택되지 않았습니다.

그래서 Iteration 2를 목표로, 규약의 적용 범위와, 태스크가 무엇을 변경하면 그 규약이 필요한지를 표로 만들었습니다. 다음은 현재 체크리스트를 일본어로 요약한 것입니다.

함께, 변경하지 않는 코드까지 일률적으로 이식할 필요는 없으며, 이번에 작성・재작성・이동하는 코드에 적용한다고 명시했습니다. 기존 SDK 관리나 공개 인터페이스를 유지하는 것과, 대체하는 화면의 오래된 구현 방식을 남기는 것도 나누었습니다.

구현 전에는 해당 규약과 구현지를 짧게 정리하고, 구현 후에는 증거를 확인할 절차를 추가했습니다.

이 변경 후, 규약 적합성은 3/11에서 9/11로 늘어났습니다. 기능 추가는 1/5에서 5/5가 되었고, Repository에서의 변환, Freezed, context.l

、型付きルートまで反映されました。

ただし、機械的チェックをすべて通過したケースは3/3から2/3へ減っています。リファクタリングで、非同期処理の完了前にProviderが破棄されると、完了後の状態更新で例外が出る実装になっていました。規約が多く反映されたことと、動作が安全になったことは、別々に確認する必要がありました。(Iteration 2의 기록)

규약이 만점이라도, 동작은 망가진다

Iteration 3에서는 규약이 11/11이 되었고, 기계적 체크도 모든 케이스를 통과했습니다. 한편, 기능 요구사항은 6/7에서 4/7로 하락했습니다. 독립적인 테스트가 다루지 않았던 결함을 채점 측이 코드에서 발견하고 있습니다.

재시행으로 다른 검색을 해버린다

기능 추가 구현에서는 재시행 버튼이 입력란의 현재 값을 사용하여 검색하고 있었습니다. 개념적으로 다음 처리입니다.

onRetry: () => search(controller.text)

예를 들어, 'Flutter'로 검색하여 실패한 후, 입력만 'Dart'로 변경하고 재시행하면, 'Dart'로 검색합니다. 태스크에서 요구했던 '실패한 검색을 재시행하는' 동작이 아니었습니다.

그래서 Skill에 재시행의 대상을 명기했습니다. Notifier로 관리한다면 실패한 리퀘스트의 인수를 저장하고, Provider family로 관리한다면 실패한 인수와 대응하는 키를 invalidate합니다. 테스트에도, 실패 후 입력을 변경하여 재시행하는 조작을 요구했습니다.

'에러 시 재시행할 수 있다'는 한 문장만으로는 무엇을 재시행할지까지 고정할 수 없었던 것입니다.

검색의 경쟁 대책에서 첫 로딩이 누락된다

리팩토링에서는 일반적인 검색에는 리퀘스트 ID에 의한 가드(guard)가 있었지만, build()로 시작하는 첫 로딩은 별도의 경로였습니다. 따라서 다음 순서로 최신 결과가 오래된 에러에 덮어씌워질 가능성이 있었습니다.

• 첫 로딩이 시작된다.
• 완료하기 전에 새로운 검색을 시작한다.
• 새로운 검색이 성공한다.
• 첫 로딩이 실패하고, 그 에러로 상태를 덮어쓴다.

수정된 Skill에서는 리퀘스트의 인수를 키로 한 Provider family를 우선하도록 했습니다. 단일 Notifier에서 인수의 변화를 다룰 경우에는, 첫 로딩도 포함한 모든 비동기 경로를 공통의 가드로 통과시키고, 성공/실패 모두 최신 리퀘스트인지, Provider가 아직 유효한지 확인하게 합니다.

Iteration 4의 기능 추가와 리팩토링은 Provider family를 채택하여 이러한 결함이 해소되었습니다. 여기서도 필요했던 것은 단순히 '경쟁을 막는 것'이 아니라, 첫 로딩/실패/파기 후 완료까지 대상을 포함하는 지시였습니다。(Iteration 3, Iteration 4)

생성 코드는 재생성하여 차이점까지 확인한다

OpenAPI 연동에서는 '생성되었다', '테스트를 실행했다'는 보고만으로는 확인할 수 없는 문제가 계속되었습니다.

초기 평가에서는 구현 측이 재생성 절차를 기재해도, 검증 측은 OpenAPI Generator를 재실행하지 않았습니다. Iteration 4부터는 두 조건에 tool/generate_api.sh을 요구하고, 다른 클린한 복사본으로 실행하여 납품된 생성 패키지와 비교하는 검사를 추가했습니다.

이는 Skill뿐만 아니라, 평가하는 메커니즘의 개선입니다. 이 시점에서 기계적 체크 내용이 바뀌었기 때문에, Iteration 1~3과 4 이후의 재생성 평가는 그대로 비교할 수 없습니다.

작업 디렉터리에서 차이점이 없어도, 클린한 복사본에서는 달라진다

Iteration 5에서는 생성 파일 12개에 포맷팅만 다른 차이점이 나왔습니다. 평가 기록에 따르면, 원인은 의존성 해결과 포맷 순서였습니다.

그 구현은, 생성 중에 DART_POST_PROCESS_FILE로 포맷하고, 나중에 dart pub get을 실행하고 있었습니다. 구현 측의 작업 디렉터리에는 이미 .dart_tool/package_config.json이 있었기 때문에, 거기에서의 재생성에서는 차이점이 나오지 않았습니다. 그러나 그것을 가지지 않은 클린한 복사본에서는 포매터가 참조하는 언어 버전 조건이 바뀌어 다른 포맷팅 결과가 나왔습니다.

이 결과를 바탕으로, 생성 패키지에서 의존성 해결 후 포맷하기, .dart_tool이나 build가 없는 복사본에서 재생성을 확인하는 것을 Skill에 추가했습니다. '다시 생성한다'만으로는 작업 중에 생긴 환경에 대한 의존성을 찾을 수 없었던 것입니다。(Iteration 5의 기록)

테스트 위치와 생성물 소유자 명확히 하기

생성 패키지의 test/ 디렉터리에 Generator가 만든 TODO 초안만 남아 실행된 경우도 있었습니다. 앱 측에 테스트 코드가 있어도, 패키지 자체의 serializer나 API 계약 검증에는 도움이 되지 않았습니다.

이에 따라 생성 코드와 패키지 테스트를 분리하여, 생성 코드는 Generator가 관리하고 패키지 테스트는 수동으로 관리하도록 했습니다. 초안 생성을 중단하거나, test/** 디렉터리를 .openapi-generator-ignore 파일에 추가하고, 실제로 누락(omission), null 처리, 값 존재 여부를 다루는 실제 테스트 코드를 배치합니다. 재생성하더라도 해당 테스트가 남아있도록 하는 것까지 검증 대상으로 삼았습니다.

또한, 생성된 pubspec.yaml 파일을 스크립트 내 Python을 사용하여 수정하여 의존성을 조정하는 실행도 있었습니다. '생성물을 수동으로 편집하지 않는다'는 지침에는 스크립트를 통한 수정도 포함된다고 명시했습니다. 수정 사항은 생성 설정이나 버전 선택에서 처리하고, 해결할 수 없는 문제는 문제로 보고하는 방침입니다.

최종적으로, 생성 패키지 단독으로 일반적인 의존성 해결, 비대화형 코드 생성, dart analyze, 그리고 실제 테스트가 성공하는 지점까지 조건을 구체화했습니다. Generator에서 비롯된 경고(warning)에 대해서도 --no-fatal-warnings 옵션으로 분석 명령을 완화하기보다는, 대상 패키지 내에서 해당 규칙을 개별적으로 설정하고 그 설정을 재생성으로부터 보호하도록 했습니다. 이는 이번 Skill에서 채택한 방식입니다. (Iteration 6, Iteration 7)

한 번에 모든 항목 통과하지 못하며 발견된 누락 사항

Iteration 8에서 처음으로 기능 요구사항 7/7, 규약 11/11, 기계적 체크 전 케이스를 모두 통과했습니다. 이에 Skill의 내용은 변경하지 않고 추가로 2회 실행했습니다.

2차 기능 추가에서는 같은 검색어를 재전송해도 새로운 검색이 시작되지 않는 문제도 있었습니다. Provider family의 키에 동일한 값을 할당하는 것만으로는 필요한 재가져오기(re-fetch)로 이어지지 못했습니다. 상세 화면 오류 표시에는 재시도(retry) 작업도 없었습니다.

이 기록을 통해, 절차 마지막에 '확인한다'고 쓰는 것보다 구현 판단에 사용되는 체크리스트의 행 자체를 구체화하는 것이 더 효과적이라고 생각했습니다. Iteration 9에서는 다음 사항들을 변경했습니다.

• Freezed 대상: 수정할 파일에 기존 공개 데이터 클래스가 있으면 대상으로 지정한다. 생성자(constructor) 시그니처를 유지해야 하는 경우에도, 대응하는 const factory로 표현한다. -
• 동일 조건 재전송: Provider family에서는 동일한 인자라도 invalidate나 refresh를 통해 새로운 요청을 시작한다. -
• 오류로부터의 복귀: 목록뿐만 아니라 상세를 포함한 모든 오류 상태에 재시도 작업을 준비한다.

Freezed 지침의 예를 들면, 변경 전후의 차이는 다음과 같습니다. 설명 목적으로 일본어로 요약했습니다.

초기 지침

도메인 모델, 앱 상태, 값 객체에는 Freezed를 사용한다.

Iteration 9에서 구체화된 지침

수정할 파일에 기존 공개 데이터 클래스가 있는 경우에도 Freezed의 대상으로 지정한다. 생성자 시그니처를 유지할 필요가 있다면, 그에 대응하는 const factory로 표현한다.

후자는 기존 클래스를 그대로 남겨두어도 되는지에 대한 구현 중 판단에 답하고 있습니다. 자신의 Skill을 개선할 때도, 누락된 규약을 강조할 뿐만 아니라 '어떤 변경이 해당 규약의 대상이 되는지'를 추가하면 테스트하기 쉬워집니다.

Reading Shelf에도 같은 검색어를 재전송했을 때 업데이트하는 처리와 그 Widget test를 추가했습니다. 문서뿐만 아니라 참조되는 샘플에도 동일한 동작을 반영하고 있습니다.

なお、Iteration 8의 첫 실행과 추가 실행 사이에는, 평가 도구 측에서 이용 가능한 Skill 목록의 변화를 감지하는 수정 사항을 적용했습니다. Skill 자체는 동일하지만, 실행 환경까지 완전히 불변했던 것은 아닙니다. (Iteration 8의 반복 평가)

Iteration 9에서는 세 번 모두 모든 항목을 통과했습니다

수정된 버전을 3회 평가한 결과입니다. 각 행은 3가지 케이스 분량의 합계이며, '기계적 체크'는 모든 검사를 통과한 케이스 수입니다.

| 실행 | 조건 | 기능 요구사항 | 규약 | 기계적 체크 |
|---|---|---|---|
| 1회차 | Skill 없음 | 6/7 | 1/11 | 1/3 |
| ... |
Skill이 있는 경우, 3회 모두 기존의 ReadingRecord가 Freezed되어 같은 검색어의 재전송이나 재시도의 누락도 재발하지 않았습니다. 재생성 차분 검사, 패키지 단독 분석 및 코드 생성, 경쟁 또는 폐기 후 완료를 확인하는 독립 테스트도 통과했습니다.

구현 시간 및 측정 토큰 수

동일한 Skill 버전을 사용한 Iteration 9의 3회분을 Skill 없음/있음으로 비교했습니다.

각 막대는 해당 회차 3가지 케이스 분량의 합계입니다. 시간은 분, 토큰 수는 만 토큰 단위로 표시했습니다. 구현 측만 집계했으며, 채점 측은 포함하지 않았습니다.

한편, 실행 비용은 증가하고 있습니다. 3회분 구현 시간의 총합은 Skill 없음이 1,985.4초, Skill 있음이 2,914.0초로 약 1.5배였습니다. 측정 토큰 수는 약 305만에서 약 957만으로 약 3.1배가 되었습니다. 이는 구현 측의 집계이며, 채점 측 비용은 포함하지 않습니다. 또한, 캐시된 입력을 포함한 토큰 수이므로 과금 금액의 비율을 나타내는 것은 아닙니다.

Skill 있음의 토큰 수는 각 회차 약 174만~457만으로 크게 변동합니다. 이번 평가에서는 품질 확인은 진행되었으나, 실행 비용과 그 편차가 다음 과제가 되었습니다. (Iteration 9 기록)

이 결과에서 알 수 있는 범위

이번에 확인된 것은 고정된 3가지 기존 앱용 태스크에 대해, 이 모델에게 Skill 세트를 명시적으로 전달했을 때의 결과입니다. 3회 모두 통과했다는 것은 한 번만의 성공보다 정보가 많지만, 모든 Flutter 개발에서의 유효성이나 통계적 신뢰성을 보여주기에는 작은 샘플입니다.

같은 케이스를 보면서 개선했기 때문에, 다른 태스크에서도 동일하게 효과가 있을지는 미확인입니다. 규약 점수도 이 Skill로 채택한 설계에 적합한지를 측정하고 있습니다. Skill 없음의 구현에서 타입이 지정된 라우트나 Freezed가 없다는 이유만으로, 그 설계 전체가 떨어진다고는 할 수 없습니다.

비교 조건에도 주의할 점이 있습니다. Iteration 1부터 2에서는 CLI가 바뀌었고, Iteration 4에서는 재생성 검사를 추가했습니다. Iteration 9의 Skill 없음 API 채점 1건에서는 실행 중에 시스템 Skill 목록이 바뀌어 일부 Skill이 유효했을 가능성이 기록되었습니다. 평가 리포트에서는 채점 로그에 Skill 사용이 없고, 다른 실행과 판정이 일치한다는 점에서 재채점하지 않고 유지했습니다. Skill 있음 실행에서는 이 목록의 변화가 기록되지 않았습니다.

또한, 구현과 채점은 같은 모델 계열로 진행되었으며, 사람에 의한 리뷰는 평가 기록상 아직 이루어지지 않았습니다. 다른 모델, 신규 프로젝트, Skill 선택 정확도, 미사용 케이스에서의 검증이 남아있습니다.

맺음말

지난번에는 자신의 설계 방침을 Skill로 언어화했습니다. 이번에는 그 지시로 실제로 무엇이 만들어지는지를 보면서, 적용 조건과 확인 방법을 구체화했습니다.

개선에 도움이 된 것은 '반드시 지켜야 한다'고 강조하는 것보다, 어떤 변경 사항이 규약의 대상인지, 어떤 동작을 유지해야 하는지, 무엇을 실행하면 확인할 수 있는지를 쓰는 것이었습니다. 실패한 검색의 인자, 첫 로딩 시의 경쟁, 클린 복사본에서의 재생성 등 모호했던 조건을 하나씩 명확히 했습니다.

그리고 한 번의 전 통과로 멈추지 않았기 때문에, 최종 체크가 실행되지 않는 경우나, 동일한 Skill이라도 기존 모델이 놓치는 경우가 무엇인지 알게 되었습니다. Skill은 지시를 작성하고 끝내는 것이 아니라, 결과물과 검증 결과를 보고 업데이트하는 것으로 다루고 싶습니다.

다음 과제는 이번 개선에 사용하지 않은 케이스로 확인해 보는 것과, 증가한 실행 비용의 원인을 조사하는 것입니다. 리포지토리에는 Skill 본체와 평가 코드, 각 Iteration의 리포트를 공개했습니다. 원본 실행 로그는 gitignore 대상으로서 로컬에 저장하고 있습니다.

토론 (Discussion)