# 프롬프트 엔지니어링 가이드북 프로젝트

## 소개

이번 프로젝트에서 시도한 것은 **프롬프트 엔지니어링을 단순한 “좋은 질문 작성법”이 아니라, AI와 함께 일하는 전체 작업 시스템으로 정리하는 가이드북 설계**입니다.

처음에는 “프롬프트 관련 가이드북을 만들자”는 아이디어에서 출발했습니다. 그런데 실제로 AI를 업무나 창작에 활용하다 보면 좋은 프롬프트 하나만으로는 한계가 있습니다. 같은 프롬프트를 써도 입력 정보가 다르면 결과가 달라지고, 도구 연결이나 검증 루프가 없으면 결과를 신뢰하기 어렵습니다.

그래서 가이드북의 핵심 구조를 다음 네 단계로 잡았습니다.

1. **Prompt Engineering** — AI에게 무엇을 어떻게 지시할 것인가

2. **Context Engineering** — AI가 참고해야 할 정보와 배경을 어떻게 구성할 것인가

3. **Harness Engineering** — AI가 일하는 실행 환경과 도구, 권한, 검증 체계를 어떻게 만들 것인가

4. **Loop Engineering** — 계획, 실행, 검증, 수정의 반복 구조를 어떻게 설계할 것인가

목표는 프롬프트 예시 모음집이 아니라, **AI를 실무에 안정적으로 활용하기 위한 사고방식과 운영 매뉴얼**을 만드는 것이었습니다.

## 진행 방법

### 사용한 도구

이번 작업에는 다음 도구와 방식을 사용했습니다.

- **Codex / ChatGPT 에이전트 환경**

가이드북 방향 설정, 목차 설계, 공식 자료 조사, 설계 문서 작성을 진행했습니다.

- **Superpowers brainstorming skill**

단순히 바로 글을 쓰지 않고, 먼저 프로젝트 목적·독자·구조·범위를 정리하는 설계 과정을 거쳤습니다.

- **웹 리서치**

OpenAI, Anthropic, LangChain 등 공식 문서를 참고해 최신 AI 활용 흐름을 확인했습니다.

- **Markdown 문서화**

최종 설계는 Markdown 파일로 저장했습니다.

작성된 설계 문서 경로는 다음과 같습니다.

```text

docs/superpowers/specs/2026-06-10-prompt-engineering-guidebook-design.md

```

### 사용한 프롬프트 전문

이번 프로젝트의 시작 프롬프트는 다음과 같습니다.

```text

$superpowers:brainstorming 프롬프트 관련해서 가이드북을 만들거야 프롬프트 엔지니어링 컨테스트엔지니어링 하네스 엔지니어링 루프엔지니어링을 모두 조사하고 활용방법등을 만들어보자

```

이후 진행 방식에 대해 다음과 같이 지시했습니다.

```text

모든 질문에 대해서는 너의 추천과 승인으로 진행하자

```

그리고 다음 단계 진행을 위해 다시 다음과 같이 지시했습니다.

```text

너의 추천과 나의 자동승인으로 끝까지 너의 추천대로 진행하라

```

마지막으로, 지피터스나 커뮤니티 제출용 글 형식에 맞추기 위해 다음 양식을 제공했습니다.

```text

소개

시도하고자 했던 것과 그 이유를 알려주세요.

진행 방법

어떤 도구를 사용했고, 어떻게 활용하셨나요?

Tip: 사용한 프롬프트 전문을 꼭 포함하고, 내용을 짧게 소개해 주세요.

Tip: 활용 이미지나 캡처 화면을 꼭 남겨주세요.

Tip: 코드 전문은 코드블록에 감싸서 작성해주세요.

결과와 배운 점

배운 점과 나만의 꿀팁을 알려주세요.

과정 중에 어떤 시행착오를 겪었나요?

도움이 필요한 부분이 있나요?

앞으로의 계획이 있다면 들려주세요.

도움 받은 글 (옵션)

참고한 지피터스 글이나 외부 사례를 알려주세요.

```

### 작업 흐름

작업은 다음 순서로 진행했습니다.

1. 현재 책/문서 작업 폴더 구조 확인

2. 기존 원고 프로젝트와 문서 작성 방식 파악

3. 프롬프트 가이드북의 1차 독자 설정

4. 공식 자료 기반으로 핵심 개념 조사

5. 2~3가지 구성 방식 비교

6. 최종적으로 4계층 구조 채택

7. 목차, 장별 구성, 검증 기준 정리

8. Markdown 설계 문서 작성

9. 설계 문서 자체 검토

10. Git 커밋으로 버전 관리

### 활용 이미지나 캡처 화면

실제 제출 시에는 아래 화면을 캡처해 첨부하면 좋습니다.

- Codex/ChatGPT에서 처음 프롬프트를 입력한 화면

- docs/superpowers/specs/2026-06-10-prompt-engineering-guidebook-design.md 파일이 열린 화면

- 생성된 목차 부분 화면

- Git 커밋 기록 화면

이 글에는 이미지 파일을 직접 첨부하지 않았지만, 제출용으로는 위 네 장면을 캡처하면 프로젝트 과정이 잘 드러납니다.

## 결과와 배운 점

### 결과

결과물로는 **프롬프트 엔지니어링 가이드북 설계서**가 만들어졌습니다.

가이드북의 큰 목차는 다음과 같이 구성했습니다.

```text

0부. 왜 프롬프트만으로는 부족한가

1부. Prompt Engineering — 지시를 명확하게 만드는 기술

2부. Context Engineering — 모델이 볼 세계를 설계하는 기술

3부. Harness Engineering — AI가 일하는 환경을 설계하는 기술

4부. Loop Engineering — 품질을 누적하는 반복 구조

5부. 실전 플레이북

부록. 템플릿, 체크리스트, 실패 진단표, 용어집

```

이 구조를 통해 프롬프트 작성법에서 시작해, 컨텍스트 구성, 실행 환경 설계, 반복 검증 루프까지 자연스럽게 확장할 수 있게 되었습니다.

### 배운 점

가장 크게 배운 점은 **좋은 AI 활용은 프롬프트 하나가 아니라 시스템 설계에 가깝다**는 것입니다.

예전에는 결과가 마음에 들지 않으면 프롬프트 문장을 더 길게 고치거나, 더 자세히 지시하는 방식으로 접근했습니다. 하지만 조사하면서 다음 사실을 다시 확인했습니다.

- 프롬프트가 좋아도 컨텍스트가 부실하면 결과가 흔들립니다.

- 컨텍스트가 좋아도 검증 루프가 없으면 결과를 신뢰하기 어렵습니다.

- 도구와 권한, 상태 관리가 없으면 에이전트 작업은 장기적으로 불안정합니다.

- 결국 AI 활용 능력은 “질문 잘하기”에서 “작업 구조 설계하기”로 확장됩니다.

### 나만의 꿀팁

이번 작업에서 얻은 팁은 다음과 같습니다.

1. **프롬프트를 쓰기 전에 산출물 형식을 먼저 정한다.**

“좋은 글을 써줘”보다 “소개, 진행 방법, 결과와 배운 점, 참고자료 형식으로 써줘”가 훨씬 안정적입니다.

2. **AI에게 질문을 맡길 때도 최종 승인 기준을 알려준다.**

이번에는 “너의 추천과 나의 자동승인”이라는 방식으로 진행했습니다. 덕분에 매번 사소한 선택에서 멈추지 않고 빠르게 설계가 진행됐습니다.

3. **프롬프트 엔지니어링을 더 큰 구조 안에 넣는다.**

Prompt, Context, Harness, Loop 네 단계로 나누면 AI 활용 실패 원인을 더 잘 진단할 수 있습니다.

4. **처음부터 완성 원고를 쓰지 말고 설계서를 먼저 만든다.**

목차, 독자, 범위, 검증 기준을 먼저 정하면 이후 집필 속도가 훨씬 빨라집니다.

### 시행착오

작업 중 가장 큰 시행착오는 **범위가 너무 넓어질 수 있다는 점**이었습니다.

프롬프트 엔지니어링만 다뤄도 책 한 권이 될 수 있는데, 여기에 컨텍스트 엔지니어링, 하네스 엔지니어링, 루프 엔지니어링까지 포함하면 쉽게 산만해질 수 있습니다.

이를 해결하기 위해 “네 개의 독립 주제”가 아니라 **AI 작업 시스템이 성숙해지는 네 단계**로 재구성했습니다.

또 하나의 시행착오는 커밋 과정에서 의도하지 않은 다른 파일 변경이 함께 포함될 뻔한 점입니다. 이후 커밋을 되돌리고 설계 문서 하나만 다시 커밋해 범위를 정리했습니다. 이 경험을 통해 AI 작업에서도 Git 상태 확인과 커밋 범위 관리가 중요하다는 점을 다시 느꼈습니다.

### 도움이 필요한 부분

앞으로 도움이 필요한 부분은 다음과 같습니다.

- 실제 독자들이 가장 궁금해하는 프롬프트 활용 사례 수집

- 업무 자동화, 리서치, 글쓰기, 코딩 등 분야별 예제 확보

- 각 장에 들어갈 실전 템플릿 검증

- 한국어 독자에게 자연스러운 용어 번역 기준 정리

특히 “컨텍스트 엔지니어링”, “하네스 엔지니어링”, “루프 엔지니어링”은 아직 한국어권에서 널리 합의된 표현이 아니기 때문에, 독자가 쉽게 이해할 수 있는 설명과 예시가 필요합니다.

### 앞으로의 계획

다음 단계에서는 설계서를 바탕으로 실제 원고를 작성할 예정입니다.

계획은 다음과 같습니다.

1. 공식 문서와 사례를 더 정리해 참고자료 목록 만들기

2. 각 장별 핵심 메시지와 예제 프롬프트 작성