Coroid는사양 중심 개발 방식을 사용합니다. 즉, 사양은 계획 단계부터 테스트 및 리뷰에 이르기까지 하나의 작업과 함께 유지되므로 모든 단계에서 동일한 성공 정의를 바탕으로 진행됩니다.
문장으로 시작하여 코딩 중에 세부 내용을 결정하는 대신, Coroid는 요청을 명확한 범위, 제외 항목 및 수락 기준으로 전환합니다. 해당 문서는 계획, 구현, 테스트 및 최종 리뷰의 근거가 됩니다.
사양 중심 개발 방식이란 무엇인가요?
사양 중심 개발 방식은 합의된且검증 가능한 결과물 기술을 바탕으로 소프트웨어를 구축하는 방법입니다. 사양에는 어떤 부분이 변경될지, 어떤 부분은 변경되지 않을지, 적용되는 제약 조건 및 리뷰어가 작업 성공 여부를 판단할 수 있는 기준이 명시되어 있습니다.
이 방식은 서로 혼동하기 쉬운 두 가지 결정을 분리합니다:
- 해당사양은 성공의 의미를 정의합니다.
- 반면구현 계획은 이를 달성하는 방법을 정의합니다.
이러한 분리는 코드 작성 전에 범위를 수정할 수 있게 하며, 너무 일찍 구현 방식을 미리 지정하지 않도록 합니다. Coroid에서는 계획 수립 전에 의도와 사양을 승인하고자 할 때 선택적SDLC 워크플로우를 활성화할 수도 있습니다.
Coroid에서의 워크플로우 작동 방식
- **결과물을 기술하세요.**Coroid에게 필요한 결과, 관련 맥락, 제약 조건 및 비목표 항목을 제공하세요.
- **사양을 검토하세요.**작업의 "사양" 탭에서 범위, 제외 항목 및 수락 기준을 확인하세요.사양탭
- **계획을 승인하세요.**설계자가 합의된 결과물을 순차적인 구현 단계로 전환합니다.
- **구축 및 검증하세요.**개발자 및 QA 에이전트는 동일한 기준을 바탕으로 변경 사항을 구현하고 약속된 동작이 올바르게 수행되는지 증명합니다.
- **pull request를 리뷰하세요.**배포된 변경 사항에는 계획, 테스트 결과, 발견 사항 및 증거가 원래의 사양과 함께 포함됩니다.
그 결과는 제품 의도부터 코드 및 인간 리뷰어가 확인하는 증거에 이르는 추적 가능성을 확보할 수 있습니다. 전체 실행 경로는 "작업이 어떻게 __COROID_TERM_0__가 되는가"에서 확인하세요.작업이 어떻게 pull request가 되는가를 참고하여 전체 실행 경로를 확인하세요.
왜 이 추가 단계가 필요한가요?
"사용자 조회 기능에 캐싱을 추가하라"와 같은 지시에는 최소 네 가지의 타당한 구현 방안이 있으며 완료 기준도 명시되어 있지 않습니다. 에이전트는 그중 하나를 선택할 것입니다. 해당 선택이 귀하가 원하는 방안일지는 운에 달려 있습니다.
사양을 통해 구현 시작 전에, 마음을 바꾸기 가장 쉬운 시점에 해당 선택지를 명확히 할 수 있습니다.
또한 검증을 위한 기준도 제공합니다. 수락 기준이 없다면 "이것이 제대로 작동하는가?"라는 질문은 "테스트가 여전히 통과되는가?"로 축소되며, 이는 훨씬 더 취약한 질문입니다.
사양에 포함되는 내용
| 구성 요소 | 답변하는 내용 |
|---|---|
| 범위 | 변경 사항은 무엇인가요? |
| 범위에 포함되지 않는 항목 | 의도적으로 제외할 항목으로 변경이 확산되는 것을 방지합니다. |
| 수용 기준 | 작업이 제대로 완료되었는지 확인하는 방법 |
| 배경 정보 | 적용되는 제약 조건, 규칙 및 기존 결정 사항 |
해당 작업의 [Specification] 탭에서 내용을 확인하고 편집할 수 있습니다.사양실행 시작 전에 해당 탭을 확인하세요. 이 프로세스에 필요한 작업 설명 및 관련 배경 정보는 __COROID_ARG_0__를 참조하세요.필요한 내용을 기술하는 방법.
실제 사례: 요약본부터 테스트 가능한 사양까지
원래의 요약본은 다음과 같다고 가정해 보겠습니다:
Add caching to the user lookup so repeated requests are faster.이 내용은 원하는 결과를 명시하지만 중요한 선택 사항들은 미결정 상태로 남깁니다. 유용한 사양은 이러한 선택 사항들을 경계와 검증 기준으로 전환합니다:
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.이제 계획 수립 담당자는 구현 방안을 선택할 수 있고, QA 담당자는 해당 기준을 바탕으로 테스트를 작성하며, 리뷰어는 pull request와 약속된 동작을 비교할 수 있습니다.
좋은 수용 기준의 조건은 무엇인가요?
대화에 참여하지 않은 사람도 확인할 수 있어야 합니다.
부족한 예:
Caching works correctly and performance is improved.우수한 예:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.두 번째 버전은 개발 에이전트에게 구현할 내용을, QA 에이전트에게 테스트할 내용을, 그리고 사용자에게는 pull request에서 확인할 사항을 명확히 알려줍니다. 첫 번째 예시는 이러한 결정 사항들을 모두 미정으로 남깁니다.
기준선 설정은 수용 기준만큼이나 중요합니다
pull request가 지나치게 커지는 가장 흔한 원인은 에이전트가 요약본을 초과해서 처리하기 때문이 아니라, 사양에 요약본의 종료 지점이 명시되어 있지 않기 때문입니다.
해당 모듈을 리팩토링하지 않기를 원한다면 반드시 명시하세요. '호출 지점을 변경하지 마세요'라는 문구는 합법적이고 유용한 기준입니다.
흔히 발생하는 사양 작성 오류
| 오류 | 더 나은 접근 방식 |
|---|---|
| 결과가 아닌 구현 방안을 기술하는 경우 | 동작 방식과 제약 조건을 명시한 뒤 계획 수립 담당자가 구현 방안을 선택하도록 하세요. |
| '빠르다', '안전하다', '정상적으로 작동한다'와 같은 표현을 사용하는 경우 | 이러한 표현 대신 관찰 가능한 임계값, 동작 또는 테스트로 대체하세요. |
| 포함하지 않을 항목을 명시하지 않는 경우 | 변경 없이 그대로 유지되어야 하는 인접 코드, 인터페이스 또는 동작을 명시하세요. |
| 관련 없는 결과를 하나의 사양에 포함시키는 경우 | 작업을 분할하여 하나의 pull request에서 한 번에 리뷰할 수 있도록 하세요. |
| 가정 사항을 확인하지 않고 티켓을 복사하는 경우 | 저장소에서는 파악할 수 없는 배경 정보와 결정 사항을 추가하세요. |
사양 내용에 동의하지 않는 경우
사양을 수정하세요. 사양은 실행이 시작되기 전까지는 계속 수정 가능한 문서이며, 이를 수정하는 것이 사양에 따라 작성된 코드를 수정하는 것보다 훨씬 저렴합니다.
사양을 검토한 결과 작업이 실제로 두 개로 나뉘는 경우, 이를 두 개의 작업으로 분할하세요. 각 작업은 하나의 pull request로 완료되어 한 사람이 한 번에 리뷰할 수 있어야 합니다.
향후 진행 방향
소규모 변경을 넘어서는 모든 작업의 경우 사양서가 곧 계획이 됩니다. 자세히 보기작업, 계획, 스프린트 및 진행 단계, 이를 통해 코드 작성 전에 작업이 어떻게 분할되고 승인되는지 설명합니다.
자주 묻는 질문
사양서는 기술 설계와 동일한 것인가요?
아닙니다. 사양서는 요구되는 결과와 경계를 정의합니다. 기술 설계 또는 구현 계획은 해당 결과를 달성하기 위해 사용되는 아키텍처와 단계를 설명합니다.
모든 변경 사항에 긴 사양서가 필요한가요?
아닙니다. 명확한 소규모 변경의 경우 몇 줄의 범위 정의와 수용 기준만으로 충분할 수 있습니다. 사양서는 불필요한 절차를 추가하는 것이 아니라 의미 있는 불확실성을 제거해야 합니다.
누가 사양서를 승인해야 하나요?
결과에 대한 책임이 있는 사람이 해당 범위와 기준이 팀의 요구사항에 부합하는지 확인해야 합니다. 해당 제약 조건이 성공에 영향을 미치는 경우 기술, 보안 또는 컴플라이언스 담당 승인자가 참여할 수 있습니다.
작업 시작 후에도 사양서를 변경할 수 있나요?
변경은 가능하지만, 새로운 버전을 생성하고 종속된 계획 및 작업에 대한 리뷰를 진행해야 합니다. 명시하지 않은 범위 변경은 요청 내용과 완성된 pull request 간의 증거 체계를 훼손합니다.