스팀 앱 개발기 #170 - 작성 완료: SDS API 추가 연동을 위한 프롬프트 작성 방법

작성 완료: SDS API 추가 연동을 위한 프롬프트 작성 방법

---

스팀 파워 임대 리스트를 구현할 때부터 SDS API를 사용하기 시작했습니다. 앞으로도 이를 종종 사용할 예정이며, 보다 편리하고 빠른 실행을 위해 정형화된 프롬프트를 정리하였습니다. 이 또한 Claude Code가 지난 데이터들을 기반으로 만들어 준 것입니다.

---

5. API 추가 연동을 위한 프롬프트 작성 방법

이 문서는 사람이 읽는 절차서이면서, Claude Code에게 주는 지시의 근거 문서이기도
하다. 따라서 새 엔드포인트를 붙일 때 절차를 다시 설명할 필요가 없다. 이 문서를
가리키고, 이 엔드포인트에만 해당하는 정보만 채워서 주는 것이 프롬프트의 전부다.

5.1 프롬프트에 반드시 들어가야 하는 것

레이어 구조, DTO 패턴, 에러 처리, 네이밍 규칙은 이 문서와 CLAUDE.md에 이미 있다.
프롬프트가 담당할 몫은 문서가 알 수 없는 것들뿐이다.

#	항목	왜 필요한가	빠뜨리면 생기는 일
1	실제 값이 들어간 전체 URL 1개	경로 파라미터의 개수·순서를 URL로만 알 수 있다	@Path 순서를 틀린다
2	응답 예시 (성공 1건 + 에러 1건)	cols의 키·순서·타입을 아는 유일한 근거	매핑 인덱스와 타입을 추측한다
3	용도와 붙일 화면	도메인 모델의 필드와 포맷이 여기서 결정된다	화면이 다시 가공해야 하는 모델이 나온다
4	정렬·페이징 계약	최신순 보장 여부에 따라 구현이 갈린다 (§2-5)	화면에 오래된 데이터가 먼저 나온다
5	VESTS 포함 여부	DGP 병렬 호출이 필요한지 결정된다	VESTS 원시값이 그대로 화면에 노출된다
6	기능 이름(단수/복수)	파일 10개의 이름이 전부 여기서 파생된다	기존 네이밍과 어긋난다
7	어느 단계까지 할지	한 번에 화면까지 갈지, DTO까지만 할지	리뷰 없이 10개 파일이 한꺼번에 생성된다

2번은 직접 curl로 받은 실제 응답을 붙여넣는다. SDS는 op별로 cols가 다르고
(§2-3) 문서에 스키마가 없으므로, 응답 예시가 없으면 어떤 프롬프트를 써도 매핑은
추측이 된다. Step 0을 사람이 먼저 하고 그 결과를 프롬프트에 넣는 것이 가장 빠르다.

5.2 프롬프트 템플릿

scripts/integrate-steemworld-api.md의 절차대로 SteemWorld API를 연동해줘.

- 엔드포인트: https://sds.steemworld.org/{api}/{method}/{실제 값이 들어간 전체 경로}
- 경로 파라미터: {이름} = {의미}, ... (기본값이 있으면 함께)
- 용도: {어떤 화면의 무엇을 그리는가}
- 정렬/페이징: {최신순 보장 여부, orderBy·orderDir 지원 여부, limit 초과 시 잘리는 방향}
- 보관 기간: {해당 API 페이지의 store_history_days / store_days, 없으면 생략}
- VESTS 환산: {필요 / 불필요}
- 이름: {Xxx} (DTO·모델·UseCase 이름의 기준)
- 범위: Step {n}까지

성공 응답:
```json
{여기에 curl 결과 붙여넣기}
```

에러 응답(무효 계정):
```json
{여기에 curl 결과 붙여넣기}
```

5.3 실제 예시

followers_api/getFollowHistory(이 계정이 누구를 팔로우했는지의 이력)를 붙인다고 할 때.

scripts/integrate-steemworld-api.md의 절차대로 SteemWorld API를 연동해줘.

- 엔드포인트: https://sds.steemworld.org/followers_api/getFollowHistory/steemchiller/1-9999999999/50/0
- 경로 파라미터: source=계정, fromTime-toTime=조회 범위(초), limit=50 기본, offset=0 기본
- 용도: 계정 상세 화면에 "팔로우 이력" 탭을 추가한다. 시간과 팔로우한 계정을 보여준다.
- 정렬/페이징: 시간 오름차순 고정, orderBy·orderDir 없음. 최신순 목록이 필요하므로
  범위를 끝까지 읽고 클라이언트에서 뒤집는 rewards_api 패턴(Step 5-c)을 따른다.
- 보관 기간: store_history_days = 90. 90일 이전 데이터는 없다는 점을 주석에 남겨줘.
- VESTS 환산: 불필요
- 이름: FollowHistory
- 범위: Step 6(UseCase)까지. ViewModel과 화면은 다음에 별도로 요청할게.

성공 응답:
```json
{"code":0,"result":{"cols":{"time":0,"target":1},"rows":[[1783594500,"bountyking5"],[1784041863,"kafio"]]}}
```

에러 응답(무효 계정):
```json
{"code":-1,"error":"Account id for 'invalid10293845' does not exist"}
```

cols가 {"time":0,"target":1} 두 개뿐이라는 것, rows의 첫 값이 Unix timestamp라는
것, 무효 계정도 HTTP 200으로 온다는 것 — 이 세 가지가 프롬프트가 실제로 전달하는
정보의 전부다. 나머지는 문서가 이미 알고 있다.

5.4 단계를 나눠서 요청한다

10개 파일을 한 프롬프트로 만들면 초반의 매핑 실수가 UseCase·화면까지 그대로
번진다. 다음 세 덩어리로 끊어 요청하고, 각 덩어리 끝에서 확인한다.

요청	범위	끝나면 확인할 것
1차	Step 1~2 (DTO·도메인 모델)	cols 인덱스 매핑, 기본 인덱스 상수, 하단 JSON 예시 주석
2차	Step 3~6 (Service·Repository·UseCase) + Step 10(a)(b) 테스트	isSuccessful과 body.code 이중 확인, 테스트 통과
3차	Step 8~9 (ViewModel·화면)	State 3분기 처리, @Preview

2차까지 끝나면 테스트가 실제 API를 호출하므로, 화면을 붙이기 전에 연동이 맞는지를
테스트로 먼저 확인할 수 있다. 이 순서를 지키는 것이 프롬프트 품질보다 중요하다.

5.5 프롬프트에 쓰지 않아도 되는 것

다음은 이미 문서에 있으므로 반복해서 적지 않는다. 반복하면 문서와 프롬프트가
따로 놀기 시작하고, 규칙이 바뀌었을 때 고칠 곳이 두 군데가 된다.

• "Clean Architecture를 지켜줘", "DTO를 UI에 노출하지 마" → §3, CLAUDE.md
• "ApiResult로 감싸줘", "withContext(dispatcher)를 써줘" → Step 5, Step 6
• "에러를 HTTP 200으로 준다" → §2-1
• "숫자는 Double로 온다" → §2-4
• "테스트는 정상/무효 계정 둘 다" → Step 10

규칙 자체를 바꾸고 싶을 때는 프롬프트에 예외를 적지 말고 이 문서를 고친다.

5.6 검증까지 프롬프트에 넣는다

생성 요청의 마지막에 다음 한 줄을 붙이면 사람이 따로 돌릴 필요가 없다.

작업 후 ./gradlew :dorian-steem-data:test --tests "*ReadXxxUseCaseTest*" 와 ./gradlew build 를 실행하고 결과를 보여줘.

테스트는 실제 네트워크를 호출하므로(§Step 10) 실패가 곧 코드 버그는 아니다.
실패했을 때는 응답 본문을 함께 확인하고, 계정 데이터 변화 때문인지 매핑 오류인지
구분해서 판단한다.

---

GitHub Commit

보다 자세한 코드 또는 변경 내용은 아래 commit을 참고하세요.

• Docs: Add a prompt-writing guide for new SteemWorld endpoints

---

지난 스팀 앱 개발기

• #169 - 개발 완료: 포스트 리스트 로딩시 발생하는 오류 해결
• #168 - 작성 완료: iCloud 충돌 사본 차단
• #167 - 작성 완료: 문서 추가 정리
• #166 - 작성 완료: 문서 추가 정리
• #165 - 개발 완료: 지갑 화면에 보상 탭 도입 (저자 및 큐레이션 보상)
• #164 - 개발 완료: 저자/큐레이션 보상 내역 API 연동 (SDS API)
• #163 - 개발 완료: 지갑 화면에 탭 도입 (잔액, 보낸 목록, 받은 목록)
• #162 - 개발 완료: 패키지 관련 오류 수정
• #161 - 개발 완료: 피임대 중인 스팀 파워 목록 화면 구현
• #160 - 개발 완료: 스팀 파워 임대 목록 화면 구현
• #159 - 개발 완료: 포스트의 댓글 정렬 오류 수정
• #158 - 개발 완료: 추가 개선 6, 7, 8, 9
• #157 - 개발 완료: 추가 개선 4, 5
• #156 - 개발 완료: 추가 개선 1, 2, 3
• #155 - 개발 계획: 추가 개선 적용
• #154 - 개발 완료: 테스트 코드 개선
• #153 - 개발 완료: Architecture 개선 작업
• #152 - 개발 완료: 레거시 의존성 제거 작업 요약
• #151 - 개발 완료: Compose 마이그레이션 연장선
• #1 ~ #150

---