lesson-learned

lesson-learned 스킬 개요

lesson-learned 스킬은 최근 Git 활동을 바탕으로 소프트웨어 엔지니어링 관점의 구체적인 교훈을 뽑아냅니다. 추상적인 조언을 늘어놓는 대신, 실제 diff, 커밋 히스토리, 변경된 파일을 살펴보고 SRP, DRY, KISS, YAGNI 같은 명명된 원칙과 관련 안티패턴에 연결해 해석합니다. 그래서 lesson-learned 스킬은 이미 코드를 바꿔본 개발자가 “이번 작업에서 무엇을 배웠는가?”, “어떤 트레이드오프를 선택했는가?”, “다음에는 무엇을 반복하거나 피해야 하는가?”를 답하고 싶을 때 가장 빛납니다.

lesson-learned 스킬이 잘 맞는 사람

특히 잘 맞는 독자는 다음과 같습니다.

• 기능 개발, 리팩터링, 버그 수정, 정리를 막 끝낸 개발자
• PR 이후 학습 중심 요약을 보고 싶은 리뷰어
• 가볍게라도 엔지니어링 회고 습관을 만들고 싶은 팀 리드
• 최근 코드 변경의 원칙적 배경까지 설명해야 하는 에이전트

실제 저장소 히스토리에 근거한 설계 회고가 필요하다면, lesson-learned skill은 일반적인 “이 코드 리뷰해줘” 프롬프트보다 훨씬 강합니다.

이 스킬이 실제로 해주는 일

이 스킬의 핵심 역할은 일반적인 의미의 합격/불합격 코드 리뷰가 아닙니다. lesson-learned는 완료된 작업이나 진행 중인 작업을 뒤돌아보며, diff로 뒷받침되는 1~3개의 교훈을 추출합니다. 좋은 결과물에는 보통 다음이 들어갑니다.

• 원칙 이름
• 변경이 그 원칙을 어떻게 보여주는지
• 왜 중요한지
• 다음 단계 추천

이런 구조 덕분에 회고, 멘토링, PR 학습 노트에 특히 유용합니다.

lesson-learned와 일반 프롬프트의 차이

가장 중요한 차이는 두 가지입니다.

1. Git 히스토리를 기준으로 움직이기 때문에, 가상의 코드 조각이 아니라 실제 변경을 분석합니다.
2. 원칙 카탈로그를 전제로 하며, 특히 references/se-principles.md를 통해 패턴에 일관된 이름을 붙일 수 있는 어휘를 확보합니다.

이 조합 덕분에 결과가 소프트웨어 공학 교과서에서 복붙한 문장처럼 보이지 않고, 실제 코드 변화에서 자연스럽게 도출된 교훈처럼 읽힙니다.

lesson-learned를 고르지 말아야 할 때

실제 목적이 아래와 같다면 lesson-learned는 건너뛰는 편이 낫습니다.

• 머지 전 라인 단위 버그 탐지
• 보안 감사
• 스타일 위주의 lint 피드백
• 아직 코드 변경이 없는 상태에서의 아키텍처 설계
• 범위가 불명확한 대규모 코드베이스 검토

이런 경우에는 코드 리뷰, 보안, 설계 계열 스킬이 보통 더 적절한 첫 선택입니다.

lesson-learned 스킬 사용 방법

lesson-learned 설치 맥락

저장소에는 skills/lesson-learned/SKILL.md 안에 전용 설치 명령이 따로 적혀 있지 않으므로, 실제 설치 방식은 softaworks/agent-toolkit에서 스킬을 어떻게 불러오는지에 따라 달라집니다. 사용 환경이 해당 저장소에서 스킬 추가를 지원한다면, 일반적인 패턴은 다음과 같습니다.

npx skills add softaworks/agent-toolkit --skill lesson-learned

에이전트가 저장소에서 직접 스킬을 읽는 구조라면 다음 경로를 사용하면 됩니다.

skills/lesson-learned

어느 경우든 SKILL.md는 단순 README가 아니라 런타임 동작 명세로 봐야 합니다.

처음 쓰기 전에 꼭 읽을 파일

빠르게 시작하되 추측을 줄이려면, 아래 순서로 파일을 읽는 것이 좋습니다.

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

여기서 가장 놓치기 쉬운 도입 포인트가 하나 있습니다. 이 스킬은 se-principles.md를 불러오기 전에는 진행하지 말라고 명시적으로 안내합니다.

lesson-learned 스킬에 필요한 입력

lesson-learned usage는 모델이 아래 정보에 접근할 수 있을 때 가장 잘 작동합니다.

• Git 히스토리가 있는 저장소
• 현재 브랜치 이름 또는 main 같은 비교 대상
• 커밋 범위, 커밋 SHA, 브랜치 diff, 또는 워킹 트리 diff
• 변경이 큰 파일들을 살펴볼 수 있을 만큼의 파일 문맥

Git 맥락이 없으면 출력은 아주 빠르게 일반론으로 흘러갑니다.

먼저 올바른 분석 범위를 정하기

이 스킬의 품질은 결국 어떤 범위를 주느냐에 달려 있습니다. 저장소에서 제시하는 실용적인 기본값은 다음과 같습니다.

• feature branch: 브랜치 작업을 main과 비교
• main branch: 최근 5개 커밋 분석
• specific commit: 하나의 SHA 점검
• working changes: unstaged/staged diff 확인

좋은 lesson-learned guide는 이 선택을 초반에 강제로라도 분명하게 만듭니다. 범위가 흐리면 결과도 서로 무관한 교훈을 뒤섞기 쉽습니다.

더 나은 lesson-learned 사용을 위한 Git 명령

이 스킬이 전제로 삼는 워크플로는 아래처럼 익숙한 Git 뷰를 중심으로 돌아갑니다.

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

매번 모든 명령이 필요한 것은 아닙니다. 스킬이 설명해주길 원하는 작업의 이야기에 맞는 명령만 고르면 됩니다.

거친 요청을 강한 프롬프트로 바꾸기

약한 프롬프트:

“Reflect on my recent work.”

더 강한 프롬프트:

“Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs.”

이 프롬프트가 잘 먹히는 이유는 다음과 같습니다.

• 범위를 정의한다
• 스킬이 의존하는 참조 파일을 지정한다
• 분석 표면적을 제한한다
• 출력 형태를 구체화한다

Code Review용 lesson-learned 프롬프트 패턴

lesson-learned for Code Review는 일반 리뷰를 대체하는 도구가 아니라, 리뷰 뒤에 얹는 회고 레이어로 쓸 때 가장 효과적입니다. 실전에서는 아래처럼 요청하는 편이 좋습니다.

“Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point.”

단순히 막는 리뷰 코멘트가 아니라, 배우게 만드는 리뷰 코멘트를 원할 때 특히 유용합니다.

요청해두면 좋은 출력 형식

아래처럼 간결한 구조를 요청하는 것이 좋습니다.

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

이 형식은 저장소의 의도와 잘 맞고, 불필요하게 일반적인 문장 채우기를 줄여줍니다.

큰 diff를 다룰 때

PR이 크다면 스킬에게 “전부 분석해줘”라고 하지 마세요. 대신 다음처럼 범위를 다듬는 편이 낫습니다.

• 가장 많이 바뀐 파일을 추린다
• 변경을 주제별로 묶는다
• 뻔한 기계적 수정은 제외한다
• 교훈은 1~3개만 요청한다

이 스킬은 모든 파일 변경을 빠짐없이 목록화하는 데보다, 패턴을 뽑아내는 데 더 강합니다.

시간을 아껴주는 공통 워크플로

안정적으로 잘 먹히는 순서는 다음과 같습니다.

1. se-principles.md 로드
2. 범위 선택
3. Git log와 diff 확인
4. 가장 많이 바뀐 파일 읽기
5. 필요하면 anti-patterns.md 로드
6. 근거가 있는 1~3개 교훈 생성
7. 결과가 너무 넓거나 훈계조라면 정제

이 순서가 중요한 이유는, 원칙 카탈로그가 분석에 더 정확한 어휘를 제공하기 때문입니다.

lesson-learned 스킬 FAQ

lesson-learned는 초보자에게도 좋은가요?

네, 다만 분석할 실제 변경이 있을 때 그렇습니다. 이 스킬은 방금 자신이 한 작업을 통해 원칙을 설명해주기 때문에, 이론부터 읽는 것보다 초보자에게 더 잘 들어오는 경우가 많습니다. 반대로 저장소 접근 권한이 없거나 최근 diff가 없다면 효용이 크게 떨어집니다.

lesson-learned는 코드 리뷰와 같은가요?

아니요. lesson-learned는 회고 중심이고 원칙 지향적입니다. 코드 리뷰는 보통 정확성, 위험, 유지보수성을 중심에 둡니다. 겹치는 지점은 있지만, 결과물이 지향하는 목적 자체가 다릅니다.

lesson-learned 스킬은 Git 접근이 꼭 필요한가요?

강한 결과를 원한다면 그렇습니다. 이 저장소는 Git 히스토리와 diff를 중심으로 설계되어 있습니다. 코드 스니펫만 붙여 넣어도 원칙 관점의 코멘트는 가능하지만, 그 경우는 더 이상 이 스킬의 가장 강한 모드를 쓰는 셈은 아닙니다.

lesson-learned가 일반 프롬프트보다 나은 이유는 무엇인가요?

강점은 구조에 있습니다. 범위를 명시적으로 선택하고, 필수 원칙 참조 파일을 읽고, 교훈을 실제 코드 신호와 다시 연결하는 워크플로를 갖고 있습니다. 일반 프롬프트는 이런 기반 없이 곧바로 “best practices” 같은 일반론으로 점프하는 경우가 많습니다.

커밋하지 않은 변경에도 lesson-learned를 쓸 수 있나요?

네. 이 스킬은 git diff와 git diff --cached를 통해 워킹 변경도 다룰 수 있습니다. 그래서 커밋 전에, 지금 배포하려는 변경이 어떤 교훈이나 트레이드오프를 갖는지 미리 정리하고 싶을 때 유용합니다.

lesson-learned가 잘 맞지 않는 상황은 언제인가요?

아래와 같은 경우에는 피하는 편이 좋습니다.

• 의미 있는 최근 변경이 없다
• diff가 생성 파일이나 포매팅 노이즈가 대부분이다
• 회고보다 결함 분류가 더 중요하다
• 브랜치에 서로 무관한 작업이 많이 섞여 있다

이럴 때는 먼저 범위를 더 좁히거나, 다른 스킬을 선행하는 것이 좋습니다.

lesson-learned 스킬 개선 방법

lesson-learned가 다룰 이야기를 더 좁혀라

가장 큰 품질 레버는 범위 설정입니다. “지난 한 달 작업을 돌아봐”는 너무 넓습니다. “API 호출과 UI 렌더링을 분리한 이번 리팩터링을 돌아봐”가 훨씬 낫습니다. 범위가 좁을수록 교훈은 더 날카로운 원칙과 더 강한 근거를 갖게 됩니다.

매번 원칙 참조 파일을 먼저 로드하라

이 저장소는 이 점을 매우 분명하게 말합니다. 분석 전에 references/se-principles.md를 먼저 읽어야 합니다. 이 단계를 생략해도 모델이 관찰 자체는 할 수 있지만, 패턴에 일관된 이름을 붙이거나 널리 알려진 원칙과 연결하는 능력은 확실히 떨어집니다.

안티패턴은 균형을 위해 쓰고, 부정적으로 몰지 마라

references/anti-patterns.md는 변경에서 위험 신호가 보일 때 가장 유용합니다. 예를 들어 수정이 여기저기 흩어져 있거나, 과도한 추상화가 보이거나, “god” 모듈이 비대해질 때 그렇습니다. 결과가 징벌적으로 들리지 않도록, 표현은 완곡하게 해달라고 요청하는 편이 좋습니다.

변경 파일에 연결된 근거를 요구하라

흔한 실패 패턴은 근거 없는 상위 수준 조언입니다. lesson-learned 출력을 개선하려면 아래 요소를 명시적으로 요구하세요.

• 어떤 변경 파일이 관련되는지
• 어떤 구조적 변화가 일어났는지
• 그 변화가 어떤 트레이드오프를 뜻하는지
• 왜 그것이 특정 원칙에 대응하는지

근거가 있어야 일반적인 코멘트와 실제 교훈이 갈립니다.

교훈 개수를 제한하라

교훈이 많을수록 대개 교훈의 힘은 약해집니다. 1~3개만 요청하세요. 그래야 우선순위가 생기고, PR 노트·회고·코칭에서 실제로 쓰기 쉬우며, 결과도 더 설득력 있게 보입니다.

어떤 종류의 교훈이 필요한지 알려줘라

분석의 렌즈를 추가하면 결과 관련도가 더 높아집니다.

• maintainability lesson
• refactoring lesson
• bug-fix lesson
• design trade-off lesson
• team process lesson tied to code changes

이 방식은 스킬의 의도된 워크플로를 거스르지 않으면서도, 원하는 방향으로 분석을 유도해줍니다.

첫 결과가 일반적이면 2차 패스로 고쳐라

첫 결과가 모호하다고 해서 곧바로 처음부터 다시 돌릴 필요는 없습니다. 대신 이렇게 요청하세요.

• “Tie each lesson to a specific file or diff hunk.”
• “Replace general advice with what this branch actually demonstrates.”
• “Name the principle only if the code evidence clearly supports it.”
• “Drop any lesson that is not visible in the diff.”

대개 이런 2차 수정이, 넓게 다시 프롬프트를 짜는 것보다 더 빨리 결과를 끌어올립니다.

이런 lesson-learned 실패 패턴을 주의하라

약한 출력에서 자주 보이는 문제는 다음과 같습니다.

• 코드 근거 없이 원칙 이름만 붙인다
• 하나의 diff에서 너무 많은 교훈을 뽑는다
• 코드 리뷰 결함과 학습 포인트를 혼동한다
• 실용적 트레이드오프 대신 훈계조 문장이 나온다
• 서로 무관한 변경을 하나의 교훈으로 묶으려 한다

이런 신호를 초기에 알아차리면 수정 방향도 명확해집니다.

팀이 반복해서 쓸 때 가장 좋은 개선 경로

팀 차원에서 lesson-learned를 정기적으로 쓸 계획이라면, 아래 요소를 포함한 프롬프트 템플릿을 표준화하는 것이 좋습니다.

• scope rule
• comparison target
• maximum number of lessons
• required evidence format
• optional anti-pattern check

이렇게 하면 일관성 문제가 줄어들고, lesson-learned skill을 PR과 회고 전반에서 훨씬 더 믿고 쓸 수 있게 됩니다.