피그마 기획서 작성법 | 궈킨(Gherkin) 문법으로 개발자와 협업하는 방법

기획자마다 다른 양식, 조건 누락, 테스트 생략 등. 기획서를 둘러싼 소통 문제는 협업에서 꽤 빈번하게 벌어지는 듯하다.

나 역시 그런 문제를 겪으면서, 개발자들과 논의 끝에 궈킨(Gherkin) 문법을 기획서에 도입해보기로 했다. 

 

이번 글에서는 내가 직접 궈킨 문법을 적용했던 과정을 중심으로, 기획서 정리 방식의 변화와 실무에서의 적용 팁까지 함께 정리해보려 한다.

---

 

1. 기획서에 틀이 없던 팀, 무엇이 문제였을까?

내가 참여하던 서비스는 기획서의 양식이나 작성 방식이 전혀 통일되지 않은 상태였다.

기획자마자 설명 방식도, 기획 흐름도 제각각이라 협업자 입장에서는 매번 해석이 필요했다.

 

특히, 프론트엔드 개발자나 QA는 다음과 같은 부분에서 어려움을 겪었다.

✔️ 어떤 조건에서 이 화면이 나오는 거야?

✔️ 버튼 누르면 어디로 가는거야?

✔️ 예외 케이스는 안 적혀 있는데?

 

결과적으로 개발 일정에 차질이 생기고, QA 과정에서도 중요한 조건이 누락되는 일이 잦았다.

그래서 '조건 > 행동 > 결과'가 명확하게 드러나는 궈킨(Gherkin) 문법을 도입하게 되었다.

 

 

2. 궈킨(Gherkin) 문법이란?

Gherkin은 BDD(Behavior Driven Development, 행위 주도 개발)에서 사용하는 문서화 방식으로, 기능의 동작 흐름을 Given, When, Then 형식으로 작성하는 것이 핵심이다.

 

기본 구조 예시

Given  사용자가 로그인 페이지에 진입했을 때
When ID/PW를 입력하고 로그인 버튼을 누르면
Then 마이페이지로 이동한다

 

이 구조 덕분에 문서를 읽는 사람이 기능의 조건, 동작, 기대 결과를 정형화된 문장으로 파악할 수 있다.

 

 

3. 어떻게 도입했을까?

우리 팀에서는 화면 중심의 기획서에 궈킨 문법을 함께 적용했다.

 

1) 작성 순서

(1) UI 시안 먼저 제시 후 개발자들과 방식 협의

(2) 화면 단위로 When (어떤 행동인지) 작성

(3) 그에 대한 Then (결과) 정리

(4) 마지막으로 Given (조건) 작성

항목	예시
Given	현재 숫자가 10 미만일 때
When	사용자가 [+] 버튼을 누르면
Then	숫자가 1 증가한다

 

2) Figma 기획서 작성 방법

궈킨문법 사용한 기획서 예시

 

피그마의 컴포넌트 기능을 사용하여, 텍스트 입력 부분은 동일한 템플릿을 사용할 수 있도록 만들었다.

 

 

3) 작성 팁

• 3인칭 시점으로 작성 : 문서가 객관적으로 읽히고 테스트 케이스 작성도 수월함
• 데이터 변화 중심으로 Then 구분 : 숫자 증가, 화면 이동, 버튼 비활성화 등 하나씩 쪼개기

 

 

4. 하지만 궈킨 문법으로는 부족했던 부분

궈킨 문법은 사용자 인터렉션 중심의 구조를 표현하는 데 탁월하지만, 로직이 중요한 백엔드 개발자 입장에서는 정보가 부족하게 느껴질 수 있었다.

 

예를 들어,

포인트 적립 조건, 정산 로직, 특정 조건 분기 등은 궈킨 문법만으로는 설명이 어렵고, 반복 설명 시 비효율적

 

그래서 어떻게 보완했을까?

(1) 비즈니스 로직 문서는 컨플루언스에 따로 정리

기획서에는 관련 로직 문서로 링크 연결

 

(2) 피그잼 등 시각적 도구로 흐름도, 조건 분기 정리

복잡한 케이스는 다이어그램으로 한눈에 확인

📌 기획서는 사용자 행동 기준, 비즈니스 로직과 정책은 별도 문서화로 나누어 관리하면서, 협업자는 필요할 때 링크를 타고 상세 정보를 확인할 수 있도록 구성했다.

 

 

5. 도입 후 실제 효과

Before	After
기획서마다 형식이 달라 일관성 없음	Gherkin 기반 구조로 문서 통일
조건 누락, 예외 케이스 생략 잦음	Given - When - Then으로 명확하게 분기
테스트케이스 따로 정리 필요	기획서 자체가 테스트 문서 역할
개발 일정 추산 어려움	Then 단위로 Task 분해 ➜ 진척도 체크 쉬움
백엔드 로직 설명 누락	로직 문서 별도 링크로 구조 정리

 

 

6. 마무리 - 주니어 기획자 입장에서 느낀 점

처음에 궈킨 문법이 너무 딱딱하고 번거롭게 느껴졌지만, 한두 번 적용해보니 오히려 복잡한 흐름을 정리하는데 큰 도움이 되었다.

무엇보다 궈킨 문법을 통해 기획자, 프론트엔드 개발자, 백엔드 개발자, QA 모두 하나의 문서를 바라보며 대화할 수 있다는 것이 가장 큰 장점이었다. 

✔️ 협업 이슈가 잦다면, 기획서에 구조화된 문법 도입을 고려해보자

✔️ 궈킨 문법은 사용자 흐름을 정리하는 데 효과적이며, 테스트 문서로도 활용 가능하다

✔️ 로직 설명이 필요한 경우는 별도 문서로 보완하는 방식으로 충분히 활용할 수 있다

 

이 모든 과정에서 협업을 하는 개발자들과 논의를 거쳐서 최적의 방법을 찾는 것이 가장 좋은 방법이다.

 

 

참고 링크 모음

Medium : Gherkin for Designer

요즘IT : BDD 개념의 이해

Behavior-Driven Development

vlog : Figma를 이용한 더 나은 기획-디자이너-QA-개발 협업 방법

 

 

기획서 작성법 ❘ 궈킨(Gherkin) 문법으로 개발자와 협업하는 방법