Cursor 2탄

배경

최근 실무에서 Cursor를 다시 활용하게 되었습니다. 그동안 추가된 기능들을 살펴보며 글로 정리해 보려고 합니다.

1. Commands

1-1. commands란

commands를 사용하면 /로 실행할 수 있는 재사용 가능한 워크플로를 만들 수 있습니다. 팀 전체의 프로세스를 표준화하고, 자주 수행하는 작업을 더 효율적으로 처리하도록 도와줍니다.

1-2. .cursor/commands 안에 md 작성하기

저는 PR 생성을 자동화하고 싶어 워크플로를 아래와 같이 정의했습니다.

# PR 생성
 
## 개요
 
적절한 설명이 담긴 구조화된 풀 리퀘스트를 생성합니다.
 
## 단계
 
1. **브랜치 준비**
 
- 모든 변경사항이 커밋되었는지 확인
- 브랜치를 원격 저장소에 푸시
- 브랜치가 develop과 최신 상태인지 확인
 
2. **PR 설명 작성**
 
- PR 템플릿은 `.github/PULL_REQUEST_TEMPLATE.md` 참고
- 템플릿에 없는 항목은 절대 작성하지 않음
- 템플릿에 있는 항목 중 작성할 내용이 없으면 해당 항목 제거(ex. 기타 사항 제거)
- 변경사항을 명확하게 요약
- 맥락과 동기 포함
- 주요 변경사항(breaking changes) 나열
- 커밋 메시지에서 지라 티켓 번호 확인하여 링크 추가
- 지라 티켓에서 피그마, 기획서 링크 확인하여 추가
- 희망 리뷰 완료일은 오늘로부터 1영업일 후로 설정
 
3. **PR 설정**
 
- 설명이 포함된 제목으로 PR 생성
- 제목에 feat, chore 등 작성 금지

1-3. commands에 필요한 MCP 연결하기

앞서 정의한 create-pr.md 파일에는 다음 정보를 자동으로 포함하도록 설계했습니다.

• 지라 티켓 번호 기반 링크 추가
• 티켓 내 피그마, 기획서 링크 자동 참조

이를 위해서는 Cursor가 외부 도구에 접근할 수 있어야 합니다. 기본 상태에서는 Jira나 Confluence에 접근할 수 없기 때문에 MCP 서버를 연결했습니다.

연결 방법은 매우 간단합니다. 우선 우측 설정 버튼 클릭 혹은 Cmd+Shift+J로 Cursor 설정을 엽니다. mcp-atlassian의 Quick Start 가이드를 참고해 URL, USERNAME, API_TOKEN 정도를 채워주면 MCP를 연동할 수 있습니다. 참고로 Jira API 토큰은 https://id.atlassian.com/manage-profile/security/api-tokens 에서 발급 가능합니다.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_SSL_VERIFY": "false",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "CONFLUENCE_SSL_VERIFY": "false"
      }
    }
  }
}

1-4. /로 command 실행하기

저는 Cursor로 PR을 생성했을 때 claude-4-sonnet 기준으로 8.7만 token과 0.14$가 소비되었습니다.

1-5. 레퍼런스 참고해서 우리에게 필요한 command 추가하기

• https://cursor.com/docs/context/commands#examples
• https://github.com/hamzafer/cursor-commands

저는 위 링크들을 참고해서 아래와 같은 커맨드를 추가했습니다.

- create-pr: PR 템플릿에 맞춰 구조화된 풀 리퀘스트를 생성하는 커맨드
- debug-issue: 체계적인 디버깅 프로세스를 안내하는 커맨드
- write-unit-tests: 유닛 테스트 작성 가이드라인을 제공하는 커맨드

1-6. Team commands 활용하기

Created by team admins in the Cursor Dashboard and automatically available to all team members
Team commands are available on Team and Enterprise plans.

Team/Enterprise 플랜을 사용 중이라면 Cursor Dashboard에서 Team Commands를 생성하는 것만으로 별도의 공유 없이 팀원 전체가 공용 commands를 사용할 수 있으며, 중앙에서 commands를 일괄 관리할 수 있다는 장점이 있습니다.

2. Skills, Rules, AGENTS

Cursor는 에이전트 동작을 커스텀하는 두 가지 주요 방법, Skills와 Rules를 제공합니다.

2-1. Skills: 필요할 때 불러오는 동적 기능과 워크플로우

Skills는 에이전트의 능력을 확장하는 방법입니다. SKILL.md 파일로 정의하며, 에이전트가 관련성이 있다고 판단할 때만 동적으로 로드됩니다. 덕분에 컨텍스트를 무겁게 만들지 않으면서도, 특정 작업에 필요한 전문 워크플로우를 제공할 수 있습니다. Skills에 포함될 수 있는 요소는 아래와 같습니다.

• /로 호출하는 커스텀 커맨드(반복 가능한 워크플로우)
• 에이전트 행동 전후로 실행되는 훅(Hooks)
• 특정 작업에 필요한 도메인 지식(필요 시 온디맨드로 로드)

상시 적용되는 Rules는 짧게 유지하고, 특수한 작업 능력은 Skills로 분리하는 게 추천되는 운영 방식입니다. Rules가 많아질수록 컨텍스트가 오염될 위험이 커지기 때문입니다.

https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/SKILL.md

위 파일처럼 메인 SKILL.md 파일은 핵심 내용에 집중하고, 상세한 참고 자료는 별도 파일로 분리해야 합니다. 이렇게 하면 에이전트가 필요한 시점에만 점진적으로 리소스를 로드하므로, 컨텍스트 사용량을 효율적으로 관리할 수 있습니다.

참고로 에이전트 스킬은 나이틀리 릴리스 채널에서만 사용할 수 있습니다. 채널을 전환하려면 Cursor 설정을 열고 Beta를 선택한 다음, 업데이트 채널을 Nightly로 설정해야 합니다. Nightly는 소프트웨어 개발에서 가장 최신 버전의 기능을 매일 밤 업데이트하는 버전을 의미합니다. 일반 사용자용(Stable) 버전보다 훨씬 앞선 기능들을 미리 써볼 수 있는 실험실 같은 단계라고 보시면 됩니다.

2-2. Rules: 프로젝트에 항상 적용되는 정적 컨텍스트

Rules는 프로젝트에서 에이전트가 따라야 할 기본 지침을 ‘항상 켜진 상태’로 제공하는 장치입니다. .cursor/rules/ 아래에 자주 쓰는 명령어, 코드 스타일, 작업 흐름의 핵심을 담아 마크다운 파일로 작성하면 됩니다.

# Commands
 
- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)
 
# Code style
 
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure
 
# Workflow
 
- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

Rules는 짧고 핵심적일수록 좋습니다. 스타일 가이드를 통째로 복사해 넣는 대신 린터를 쓰는 편이 낫고, 모든 명령을 나열하기보다 이 프로젝트에서 중요한 것만 남기는 편이 유지보수에 유리합니다. 특히 코드가 바뀌면 규칙도 같이 낡기 때문에, 내용 복사보다 파일 참조가 좋습니다.

피해야 할 패턴은 아래와 같습니다.

• 스타일 가이드를 통째로 Rules에 붙여 넣기(린터가 더 적합)
• 가능한 모든 명령을 문서화하기(에이전트는 이미 도구에 대해 어느 정도 알고 있기 때문)
• 거의 발생하지 않는 엣지 케이스까지 규칙으로 강제하기

2-3. AGENTS.md

현재 다양한 코딩 에이전트(Cursor, Claude, Gemini)는 각각 고유한 규칙 파일을 사용하고 있습니다.

• Cursor는 .cursor/rules
• Claude는 CLAUDE.md
• Gemini는 GEMINI.md

하나의 코딩 에이전트만 사용하지 않고, 여러 에이전트를 넘나들며 개발하는 상황이 생기면서 점점 규칙 파일 정의 및 관리가 까다로워졌습니다. 그래서 AGENTS.md가 등장했고, 이 모든 규칙 파일을 하나로 정의하고 관리할 수 있게 되었습니다.

https://agents.md 를 보면 Codex, Cursor, Gemini CLI, GitHub Copilot 등 대부분의 주요 코딩 에이전트가 AGENTS.md 를 지원하고 있습니다. 특이하게도 Claude Code는 AGENTS.md를 지원하지 않고 있는데, GitHub issue에서 거의 2,000개의 좋아요를 받았을 정도로 사용자들 사이에서 지원 요청이 많은 상태입니다. (Feature Request: Support AGENTS.md)

각 코딩 에이전트마다 파편화된 규칙 파일을 AGENTS.md로 표준화하면 일관성 측면에서 상당한 이점을 얻을 수 있습니다. 예를 들어 Cursor에서 20달러를 모두 소진해서 Copilot으로 넘어가더라도, 이미 정의된 핵심적인 컨텍스트와 규칙을 그대로 가져갈 수 있어 도구 전환에 따른 생산성 저하를 줄일 수 있습니다.

3. Agent Review

Source Control 탭에서 원하는 브랜치와 현재 브랜치를 비교하는 방식으로 변경 전체를 점검할 수도 있습니다. 라인 단위로 변경을 분석해 잠재 버그를 표시해 줍니다.

4. Debug Mode

까다로운 버그의 근본 원인을 찾고 수정하고 싶을 때 디버그 모드를 사용하면 됩니다. 코드를 바로 작성하는 대신, 에이전트가 먼저 가설을 세우고 로그 문을 추가하며 런타임 정보를 활용해 정확한 문제 지점을 특정한 뒤, 그 지점에만 집중해 수정합니다. 디버그 모드는 다음과 같은 경우에 가장 효과적입니다.

• 재현은 되지만 원인을 모르겠는 버그: 문제가 있다는 건 알지만, 코드를 읽어도 원인이 명확하지 않을 때
• 레이스 컨디션과 타이밍 이슈: 실행 순서나 비동기 동작에 따라 달라지는 문제
• 성능 문제와 메모리 누수: 런타임 프로파일링이 있어야 파악할 수 있는 이슈
• 예전에는 잘 되던 기능이 깨진 회귀 버그: 무엇이 변경되었는지 추적해야 할 때

일반적인 Agent 상호작용만으로는 버그를 잡기 어려울 때, 디버그 모드는 수정안을 추측하기보다 런타임 증거를 기반으로 한 다른 접근 방식을 제공합니다.

5. Browser

• https://cursor.com/blog/browser-visual-editor
• https://cursor.com/ko/docs/agent/browser

브라우저 기능은 최상의 성능을 위해 Sonnet 4.5, GPT-5, Auto 모델 사용을 권장한다고 하며, 자세한 내용은 아래와 같습니다.

1. 탐색: URL을 열고 웹 페이지를 탐색합니다. 에이전트는 URL을 열고, 링크를 따라가며, 방문 기록에서 앞뒤로 이동하고, 페이지를 새로고침해 웹 어디든 이동할 수 있습니다.
2. 클릭: 버튼, 링크, 폼 요소와 상호작용합니다. 에이전트는 페이지 요소를 식별하고 상호작용할 수 있으며, 보이는 모든 요소에 대해 클릭, 더블 클릭, 오른쪽 클릭, 마우스를 올리는(호버) 동작을 수행할 수 있습니다.
3. 입력: 입력 필드와 폼에 텍스트를 입력합니다. 에이전트는 폼을 작성하고 데이터를 제출하며, 폼 필드, 검색창, 텍스트 영역과 상호작용할 수 있습니다.
4. 스크롤: 긴 페이지와 콘텐츠를 탐색합니다. 에이전트는 스크롤하여 추가 콘텐츠를 표시하고, 특정 요소를 찾고, 긴 문서를 둘러볼 수 있습니다.
5. 스크린샷: 웹 페이지의 화면을 캡처합니다. 스크린샷은 에이전트가 페이지 레이아웃을 이해하고 시각적 요소를 확인하며, 브라우저에서 수행한 동작에 대한 확인 정보를 제공하는 데 도움이 됩니다.
6. 콘솔 출력: 브라우저 콘솔 메시지, 오류, 로그를 읽습니다. 에이전트는 JavaScript 오류, 디버그 출력, 네트워크 경고를 모니터링해 문제를 해결하고 페이지 동작을 검증할 수 있습니다.
7. 네트워크 트래픽: 페이지에서 발생하는 HTTP 요청과 응답을 모니터링합니다. 에이전트는 API 호출을 추적하고, 요청 페이로드를 분석하고, 응답 상태 코드를 확인하며, 네트워크 관련 문제를 진단할 수 있습니다. 이는 현재 에이전트 패널에서만 사용할 수 있으며, 곧 레이아웃에도 제공될 예정입니다.

6. Run multiple models at once

같은 프롬프트를 여러 모델에 동시에 던져 결과를 비교할 수 있습니다.

드롭다운에서 여러 모델을 선택해 실행하면 결과가 나란히 표시되고 가장 좋아 보이는 해법을 Cursor가 추천하기도 합니다.

이 방식은 모델마다 접근 방식이 달라질 수 있는 난이도 높은 문제를 다룰 때 특히 유용하며, OpenAI의 GPT 패밀리나 Anthropic의 Claude 패밀리처럼 서로 다른 모델 패밀리 간 코드 품질을 비교할 때도 효과적입니다. 또한 한 모델이 놓치기 쉬운 엣지 케이스를 탐색하는 데에도 도움이 됩니다. 병렬 실행을 많이 활용한다면 완료 알림 및 소리 설정을 함께 켜 두는 것도 좋습니다.

마치며

Cursor Docs와 Blog만 보고도 글을 작성할 수 있을 만큼 유익한 내용이 많았습니다. changelog를 통해 변화를 빠르게 파악하고 팀원들과 레슨런을 활발하게 공유한다면 생산성이 더 높아질 수 있을 것 같습니다. 정리한 내용이 실무에 도움이 되기를 바라며 글을 마치겠습니다.