본문으로 건너뛰기

일반적인 워크플로우

코드베이스 이해부터 버그 수정, 리팩터링, 테스트, 문서 작업, 서브에이전트 활용까지 자주 쓰는 패턴을 상황별로 정리했습니다.

새 코드베이스 이해하기​

전체 구조 파악​

프로젝트를 연결하고 큰 그림부터 물어보세요.

이 프로젝트의 전체 구조를 설명해줘
사용된 주요 아키텍처 패턴은 뭐야?
데이터 모델은 어디에 정의되어 있어?

처음에는 넓은 질문으로 시작해 점점 좁혀 가세요. 코드를 바꾸지 않는 질문이라 안전합니다.

팁

규모가 큰 코드베이스는 탐색 결과가 컨텍스트를 많이 차지합니다. "explore 서브에이전트로 조사하고 결과만 요약해줘"라고 요청하면 서브에이전트가 별도 컨텍스트에서 탐색합니다.

관련 코드 찾기​

사용자 인증을 처리하는 파일을 찾아줘
이 두 모듈이 어떻게 연결되는지 호출 흐름을 따라가며 설명해줘

프로젝트 지침 만들기​

/init을 실행하면 프로젝트를 분석해 AGENTS.md 초안을 만듭니다. 이후 대화마다 이 지침이 적용됩니다. 지침

버그 수정​

  1. 오류 메시지나 증상을 그대로 붙여넣습니다.

    `pnpm test`를 돌리면 이런 오류가 나: <오류 메시지>
    원인을 찾아서 고쳐줘

  2. 재현 방법과 기대 동작을 함께 알려 주면 더 정확합니다.

  3. 수정이 끝나면 테스트를 다시 돌리도록 요청합니다.

    수정한 뒤 관련 테스트를 실행해서 통과하는지 확인해줘

수동 수락 모드에서는 파일 편집마다 권한 패널이 나타납니다. 같은 폴더에서 계속 작업한다면 파일 편집은 "항상 허용"으로 두는 것이 편합니다(대화 안에서만 유효). 권한

큰 변경은 계획부터​

범위가 크거나 위험한 변경은 /plan으로 시작하세요.

  1. 입력창에서 /plan을 고르고 요구사항을 적습니다.

    /plan 결제 모듈을 새 API 버전으로 옮기고 싶어. 영향 범위와 단계를 정리해줘

  2. AI는 파일을 수정하지 않고 코드를 읽어 계획을 세웁니다. 계획은 계획 파일로 저장될 수 있습니다.

  3. 계획을 검토하고 수정을 요청합니다.

  4. 만족하면 일반 메시지로 "계획대로 1단계부터 진행해줘"라고 요청합니다.

리팩터링​

이 모듈에서 중복된 로직을 찾아서 공통 함수로 뽑아줘. 동작은 바뀌면 안 돼
`utils/date.ts`를 새 날짜 라이브러리로 바꾸고, 호출하는 곳도 모두 고쳐줘
  • 동작이 바뀌면 안 되는 작업은 테스트가 있는 상태에서 하는 것이 안전합니다.
  • 큰 리팩터링은 단계를 나눠 요청하고, 단계마다 테스트를 돌리게 하세요.
  • 되돌려야 한다면 git을 쓰세요. 헬피코드의 다시 생성은 마지막 답변에만 가능합니다.

테스트 작성​

인증 모듈에서 테스트가 없는 함수를 찾아줘
이 함수에 대한 테스트를 기존 테스트 스타일에 맞춰 작성하고 실행해줘

빌드·테스트 명령을 AGENTS.md에 적어 두면 AI가 명령을 추측하지 않습니다.

문서 다루기​

PDF, Word, Excel, PowerPoint를 첨부하고 요청합니다.

첨부한 계약서에서 해지 조항이 있는 페이지를 찾아서 요약해줘
첨부한 xlsx에서 월별 합계를 계산하는 시트를 추가해줘
이 템플릿 모양대로 10장짜리 분기 보고 덱을 만들어줘

스캔된 PDF나 표·차트는 헬피비전 OCR로 읽습니다. 파일 첨부와 문서 작업

웹 결과물 확인​

AI에게 웹 페이지나 앱을 만들게 한 뒤 확인합니다.

  1. "index.html을 만들어줘"처럼 요청하면 완성된 파일이 파일 카드로 나타납니다.
  2. 미리보기로 열거나, 브라우저 패널에서 개발 서버 주소(예: localhost:3000)를 열어 확인합니다.
  3. 수정이 필요하면 화면을 보고 말로 설명합니다.

우측 패널

서브에이전트 활용​

조사를 맡기기​

explore 서브에이전트로 결제 호출 흐름을 조사하고, 파일 경로와 핵심 함수만 요약해줘

병렬로 나눠 맡기기​

서로 독립적인 세 모듈(auth, billing, notifications)을 각각 서브에이전트로 조사해서, 공통된 문제를 정리해줘

나만의 리뷰어 만들기​

.opencode/agents/reviewer.md를 만들어 읽기 전용 리뷰 서브에이전트를 정의하세요. 서브에이전트

리뷰어 서브에이전트로 내 변경사항을 검토해줘

반복 작업을 스킬로​

같은 절차를 자주 시킨다면 스킬로 만들어 /스킬이름으로 실행합니다. 새로 만든 스킬은 /reload-skills로 바로 불러올 수 있습니다.

외부 도구 연결​

이슈 트래커, 문서, 메신저 같은 서비스를 MCP로 연결합니다. 설정 > MCP 환경설정에서 서버 URL을 등록하고, 인증이 필요하면 인증하기를 누릅니다. 이후 "이 이슈의 내용을 읽고 구현해줘"처럼 요청할 수 있습니다.

긴 대화 관리​

  • 대화가 길어지면 /compact로 요약합니다.
  • 주제가 바뀌면 새 대화를 시작하는 편이 정확하고 토큰도 아낍니다.
  • 이전 대화는 Cmd/Ctrl + K 검색으로 찾습니다.

다음 단계​