ChatGPT alternative for power users

:rocket: Serena는 LLM을 코드베이스에서 직접 작동하는 모든 기능을 갖춘 에이전트로 전환할 수 있는 강력한 코딩 에이전트 툴킷 입니다.
:wrench: Serena는 IDE의 기능과 유사한 필수적인 의미 코드 검색 및 편집 도구를 제공하며, 심볼 수준에서 코드 엔터티를 추출하고 관계적 구조를 활용합니다.
:free: Serena는 무료이며 오픈 소스로 , 이미 무료로 이용할 수 있는 LLM의 역량을 향상시킵니다.

데모

Serena가 Claude Desktop을 사용하여 간단한 기능(더 나은 로그 GUI)을 구현하는 모습을 보여줍니다. Serena의 도구를 사용하여 Claude가 원하는 기호를 찾고 편집하는 방법을 살펴보세요.

https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753

LLM 통합

Serena는 워크플로 코딩에 필요한 도구를 제공하지만, 도구 사용을 조율하는 실제 작업을 수행하려면 LLM이 필요합니다.

Serena는 여러 가지 방법으로 LLM과 통합될 수 있습니다.

모델 컨텍스트 프로토콜(MCP)을 사용하여.
Serena는 다음과 통합되는 MCP 서버를 제공합니다.
- 클로드 데스크탑,
- VSCode, Cursor 또는 IntelliJ와 같은 IDE
- Cline이나 Roo Code와 같은 확장 프로그램
- Goose(좋은 CLI 경험을 위해)
- 그리고 ChatGPT 앱을 포함한 다른 많은 앱도 곧 출시될 예정입니다.
모델에 독립적인 에이전트 프레임워크인 Agno를 사용합니다.
Serena의 Agno 기반 에이전트를 사용하면 Google, OpenAI 또는 Anthropic(유료 API 키 사용)에서 제공하는 것이든 Ollama, Together 또는 Anyscale에서 제공하는 무료 모델이든 사실상 모든 LLM을 코딩 에이전트로 전환할 수 있습니다.
Serena의 도구를 원하는 에이전트 프레임워크에 통합하여 사용할 수 있습니다.
Serena의 도구 구현은 프레임워크별 코드와 분리되어 있으므로 모든 에이전트 프레임워크에 쉽게 적용될 수 있습니다.

프로그래밍 언어 지원 및 의미 분석 기능

Serena의 시맨틱 코드 분석 기능은 널리 구현된 언어 서버 프로토콜(LSP)을 사용하는 언어 서버를 기반으로 합니다. LSP는 코드의 기호적 이해를 기반으로 다양한 코드 쿼리 및 편집 기능을 제공합니다. 이러한 기능을 갖춘 Serena는 마치 IDE 기능을 활용하는 숙련된 개발자처럼 코드를 검색하고 편집합니다. Serena는 매우 크고 복잡한 프로젝트에서도 효율적으로 적절한 컨텍스트를 찾고 필요한 작업을 수행할 수 있습니다! 따라서 무료 오픈 소스일 뿐만 아니라, 기존 유료 솔루션보다 더 나은 결과를 얻는 경우가 많습니다.

언어 서버는 다양한 프로그래밍 언어를 지원합니다. Serena를 사용하면

다음에 대한 직접적이고 즉각적인 지원:
- 파이썬
- Java( 참고 : 시작이 느립니다. 특히 초기 시작이 느립니다.)
- 타입스크립트
간접 지원(일부 코드 변경/수동 설치가 필요할 수 있음):
- 루비(테스트되지 않음)
- (테스트되지 않음)
- C# (테스트되지 않음)
- 녹(테스트 안됨)
- Kotlin(테스트되지 않음)
- 다트(테스트 안됨)
- C/C++ (테스트되지 않음) 이 언어들은 Serena가 내부적으로 사용하는 언어 서버 라이브러리 multilspy 에서 지원됩니다. 하지만 이 언어들에 대한 지원이 실제로 작동하는지 명시적으로 테스트하지는 않았습니다.

원칙적으로 새로운 언어 서버 구현을 위한 얕은 어댑터를 제공하면 추가 언어도 쉽게 지원할 수 있습니다.

세레나를 어디에 활용할 수 있나요?
세레나와 함께하는 무료 코딩 에이전트
빠른 시작
세레나의 도구 및 구성
다른 코딩 에이전트와의 비교
온보딩과 기억
다른 MCP 서버와의 결합
Serena 사용에 대한 권장 사항
문제 해결
- 세레나 로깅
감사의 말
세레나 커스터마이징
도구 전체 목록

세레나를 어디에 활용할 수 있나요?

Serena는 분석, 계획, 새로운 구성 요소 설계 또는 기존 구성 요소 리팩토링 등 모든 코딩 작업에 사용할 수 있습니다. Serena 도구를 사용하면 LLM이 인지적 인식-행동 루프를 완성할 수 있으므로, Serena 기반 에이전트는 초기 분석부터 구현, 테스트, 그리고 최종적으로 버전 제어 시스템 커밋까지 코딩 작업을 처음부터 끝까지 자율적으로 수행할 수 있습니다.

Serena는 코드를 읽고, 쓰고, 실행할 수 있으며, 로그와 터미널 출력을 읽을 수 있습니다. 권장하지는 않지만, "바이브 코딩"은 충분히 가능하며, "코드가 더 이상 존재하지 않는" 느낌을 원한다면 IDE 내부의 에이전트보다 Serena가 바이브 코딩에 더 적합하다는 것을 알게 될 것입니다. (별도의 GUI를 통해 완전히 잊을 수 있기 때문입니다.)

세레나와 함께하는 무료 코딩 에이전트

Anthropic의 Claude 무료 버전도 MCP 서버를 지원하므로 Serena를 Claude와 함께 무료로 사용할 수 있습니다. MCP 서버 지원이 추가되면 ChatGPT Desktop에서도 곧 동일한 기능을 사용할 수 있을 것으로 예상됩니다.
Agno를 사용하면 Serena를 자유/자유 중량 모델과 함께 사용할 수도 있습니다.

Serena는 Oraios AI가 개발자 커뮤니티에 기여한 결과입니다.
우리도 정기적으로 이를 사용하고 있습니다.

Windsurf나 Cursor 같은 여러 IDE 기반 구독료를 내야 해서 기존 채팅 구독료에 추가로 토큰을 구매해야 하는 상황에 지쳐버렸습니다. Claude Code, Cline, Aider 등 API 기반 도구에 드는 상당한 API 비용도 마찬가지로 매력적이지 않았습니다. 그래서 Serena를 개발할 때 다른 구독은 대부분 취소할 수 있도록 했습니다.

빠른 시작

Serena는 다양한 방법으로 사용할 수 있습니다. 아래에서 선택한 통합에 대한 지침을 확인할 수 있습니다.

Claude를 무료로 사용할 수 있는 코딩 에이전트로 바꾸고 싶다면 Claude Desktop을 통해 Serena를 사용하는 것이 좋습니다.
Gemini나 다른 모델을 사용하면서 GUI 환경을 원한다면 Agno를 사용하세요. macOS에서는 goose 의 GUI를 사용할 수도 있습니다.
CLI를 통해 Serena를 사용하는 것을 선호한다면 goose를 사용할 수 있습니다. 이 경우에도 거의 모든 모델이 가능합니다.
IDE에 통합된 Serena를 사용하려면 다른 MCP 클라이언트 섹션을 참조하세요.

설정 및 구성

uv 설치 (지침은 여기를 참조하세요 )
저장소를 /path/to/serena 로 복제합니다.
serena_config.template.yml``serena_config.yml 로 복사하고 설정을 조정합니다.
myproject.template.yml``myproject.yml 파일로 복사하고 프로젝트에 맞게 설정을 조정하세요. (Serena가 작업할 프로젝트마다 해당 파일을 하나씩 추가하세요.)
Serena가 프로젝트 간에 동적으로 전환하도록 하려면 이전 단계에서 만든 모든 프로젝트 파일 목록을 serena_config.yml 의 projects 목록에 추가합니다.

⚠️ 참고: Serena는 현재 활발하게 개발 중입니다. 지속적으로 기능을 추가하고 안정성과 UX를 개선하고 있습니다. 따라서 구성이 제대로 작동하지 않을 수 있습니다. 구성이 올바르지 않으면 MCP 서버 또는 Serena 기반 에이전트가 시작되지 않을 수 있습니다(이 경우 MCP 로그를 확인하세요). Serena를 업데이트할 때 변경 로그 와 구성 템플릿을 확인하고 구성을 적절히 수정하세요.

초기 설정 후 Serena를 사용하고 싶은 방식에 따라 아래 섹션 중 하나를 계속 진행하세요.

MCP 서버(Claude Desktop)

myproject.template.yml 의 템플릿을 기반으로 프로젝트에 대한 구성 파일(예: myproject.yml 을 만듭니다.
클라이언트에서 MCP 서버를 구성합니다.
Claude Desktop (Windows 및 macOS에서 사용 가능)의 경우, 파일 / 설정 / 개발자 / MCP 서버 / 구성 편집으로 이동하면 JSON 파일 claude_desktop_config.json 열 수 있습니다. Serena를 활성화하려면 다음 내용을 추가하세요(경로를 수정하여).지엑스피1:info: 구성에서 enable_project_activation 설정한 경우 프로젝트 파일을 전달하는 것은 선택 사항입니다. 이 설정을 사용하면 Claude에게 작업하려는 프로젝트를 활성화하도록 간단히 지시할 수 있습니다.Windows에서 경로에 백슬래시를 포함하는 경로를 사용하는 경우(슬래시만 사용할 수도 있음) 반드시 올바른 이스케이프 문자( \\ )를 사용해야 합니다.

이제 끝났습니다! 설정을 저장한 후 Claude Desktop을 다시 시작하세요.

참고: Windows 및 macOS에는 Anthropic의 공식 Claude Desktop 애플리케이션이 있고, Linux에는 오픈 소스 커뮤니티 버전이 있습니다.

⚠️ Claude Desktop 애플리케이션을 완전히 종료해야 합니다. Claude를 닫으면 시스템 트레이로 최소화됩니다. 최소한 Windows에서는 그렇습니다.

재시작 후 채팅 인터페이스에 Serena의 도구가 표시될 것입니다(작은 망치 아이콘에 주목하세요).

⚠️ 도구 이름: Claude Desktop(및 대부분의 MCP 클라이언트)은 서버 이름을 확인하지 않습니다. 따라서 "Serena 도구 사용"과 같은 명령어를 사용해서는 안 됩니다. 대신, LLM에 심볼릭 도구를 사용하거나 특정 도구의 이름을 참조하여 해당 도구를 사용하도록 지시할 수 있습니다. 또한, 여러 MCP 서버를 사용하는 경우 도구 이름 충돌이 발생하여 정의되지 않은 동작이 발생할 수 있습니다. 예를 들어, Serena는 현재 도구 이름 충돌로 인해 파일 시스템 MCP 서버 와 호환되지 않습니다.

ℹ️ stdio를 프로토콜로 사용하는 MCP 서버는 클라이언트/서버 아키텍처 측면에서 다소 특이합니다. 서버의 표준 입출력 스트림을 통해 통신하려면 클라이언트가 서버를 반드시 시작해야 하기 때문입니다. 즉, 서버를 직접 시작할 필요가 없습니다. 클라이언트 애플리케이션(예: Claude Desktop)이 이 작업을 처리하므로 실행 명령을 사용하여 구성해야 합니다.

Claude Desktop을 사용하는 MCP 서버에 대한 자세한 내용은 공식 빠른 시작 가이드를 참조하세요.

기타 MCP 클라이언트 - Cline, Roo-Code, Cursor, Windsurf 등

Serena는 MCP 서버이므로 모든 MCP 클라이언트에 포함될 수 있습니다. 위와 동일한 구성으로, 클라이언트별로 약간의 수정만 거치면 작동할 것입니다. 대부분의 기존 코딩 어시스턴트(IDE 확장 프로그램 또는 VSCode 유사 IDE)는 MCP 서버 연결을 지원합니다. Serena를 포함하면 일반적으로 심볼릭 연산 도구를 제공하여 성능이 향상됩니다.

이 경우, 사용료 청구는 Claude Desktop 클라이언트와 달리 선택한 클라이언트에서 계속 관리합니다. 하지만 다음과 같은 이유로 Serena를 이러한 방식으로 계속 사용하고 싶을 수도 있습니다.

여러분은 이미 코딩 어시스턴트(예: Cline 또는 Cursor)를 사용하고 있으며, 이를 더욱 강력하게 만들고 싶어합니다.
Linux를 사용하고 있으며 커뮤니티에서 만든 Claude Desktop을 사용하고 싶지 않습니다.
귀하는 Serena를 IDE에 더욱 긴밀하게 통합하고 싶어하며 그에 대한 비용을 지불하는 것을 꺼리지 않습니다.

Claude Desktop에서 Serena를 사용할 때와 동일한 고려 사항(특히 도구 이름 충돌)이 여기에도 적용됩니다.

코딩을 위한 AI 상호작용이 내장된 IDE 또는 확장 프로그램(사실 모든 기능이 그렇습니다)에서 Serena의 모든 도구 세트를 사용하는 경우, 사용자가 제어할 수 없는 클라이언트 내부 도구와의 원치 않는 상호작용이 발생할 수 있습니다. 특히 편집 도구의 경우, 이러한 문제가 발생할 수 있으므로 비활성화하는 것이 좋습니다. 다양한 인기 클라이언트에서 Serena를 사용하는 경험이 쌓일수록, 원활한 경험을 위한 모범 사례를 수집하고 개선해 나갈 것입니다.

거위

goose 는 MCP 서버 통합 기능을 갖춘 독립형 코딩 에이전트로, CLI(macOS에서는 GUI 포함)를 제공합니다. goose를 사용하는 것은 현재 원하는 LLM을 사용하여 CLI를 통해 Serena를 실행하는 가장 간단한 방법입니다.

여기의 지침에 따라 설치하세요.

그런 다음 goose configure 사용하여 확장 프로그램을 추가합니다. Serena를 추가하려면 Command-line Extension 옵션을 선택하고 이름을 Serena 로 지정한 후 다음을 명령으로 추가합니다.

/abs/path/to/uv run --directory /abs/path/to/serena serena-mcp-server /optional/abs/path/to/project.yml

Serena는 필요한 모든 편집 및 명령 작업을 수행할 수 있으므로 Goose가 기본적으로 활성화하는 developer 확장 프로그램을 비활성화해야 합니다.

goose configure

다시 한 번, Toggle Extensions 옵션을 선택하고 Serena가 선택되어 있고 developer 선택되어 있지 않은지 확인하세요.

이게 전부입니다. Goose의 구성 옵션을 자세히 살펴보고 무엇을 할 수 있는지 확인해 보세요(도구 실행에 대한 다양한 권한 수준을 설정하는 등 다양한 기능이 있습니다).

Goose가 세션 종료 시 MCP 서버의 Python 프로세스를 항상 제대로 종료하지 않는 것 같습니다. Goose 작업을 마친 후 Serena GUI를 비활성화하거나 실행 중인 Python 프로세스를 수동으로 정리하는 것이 좋습니다.

아그노 에이전트

Agno는 모델에 구애받지 않는 에이전트 프레임워크로, Serena를 MCP 기술과 무관하게 다수의 기본 LLM을 가진 에이전트로 전환할 수 있도록 합니다. Agno는 현재 Serena를 채팅 GUI에서 원하는 LLM으로 실행하는 가장 간단한 방법입니다(Mac을 사용하는 경우 설정이 거의 필요 없는 Goose를 선호할 수 있습니다).

Agno는 아직 완전히 안정적이지는 않지만, 자체 오픈 소스 UI를 제공하여 채팅 인터페이스를 통해 에이전트를 직접 사용하기 편리하기 때문에 선택했습니다. Agno를 사용하면 Serena가 에이전트로 전환되어(더 이상 MCP 서버가 아님) 프로그래밍 방식(예: 벤치마킹 또는 애플리케이션 내에서)으로 사용할 수 있습니다.

작동 방식은 다음과 같습니다( Agno의 문서 도 참조하세요).

npx로 agent-ui 코드 다운로드
npx create-agent-ui@latest
또는 수동으로 복제할 수도 있습니다.
git clone https://github.com/agno-agi/agent-ui.git cd agent-ui pnpm install pnpm dev
선택 사항인 Serena를 설치하세요:
# You can also only select agno,google or agno,anthropic instead of all-extras uv pip install --all-extras -r pyproject.toml -e .
.env.example``.env 로 복사하고 사용하려는 공급자에 대한 API 키를 입력합니다.
agno agent 앱을 시작하세요
uv run python scripts/agno_agent.py
기본적으로 스크립트는 Claude를 모델로 사용하지만 Agno가 지원하는 모델(기본적으로 기존 모델)을 선택할 수 있습니다.
새 터미널에서 agno UI를 시작합니다.
cd agent-ui pnpm dev
위에서 시작한 에이전트에 UI를 연결하고 채팅을 시작하세요. MCP 서버 버전과 동일한 도구를 사용할 수 있습니다.

다음은 Serena가 최신 Gemini 모델을 사용하여 간단한 분석 작업을 수행하는 짧은 데모입니다.

https://github.com/user-attachments/assets/ccfcb968-277d-4ca9-af7f-b84578858c62

⚠️ 중요: MCP 서버 방식과 달리 Agno UI의 도구 실행은 사용자의 권한을 요청하지 않습니다. 셸 도구는 임의 코드 실행이 가능하기 때문에 특히 중요합니다. Claude를 사용한 테스트에서는 이 부분에서 문제가 발생한 적이 없지만, 이를 허용하는 것이 완전히 안전하지는 않을 수 있습니다. Serena 프로젝트의 구성 파일( .yml )에서 특정 도구를 비활성화하도록 설정할 수 있습니다.

기타 에이전트 프레임워크

Agno 에이전트는 Agno UI 덕분에 특히 훌륭하지만, Serena는 어떤 에이전트 프레임워크(예: pydantic-ai , langgraph 등)에나 쉽게 통합할 수 있습니다.

SerenaAgnoToolkit 에서 agno를 위해 우리가 한 것처럼, Serena의 도구를 원하는 프레임워크의 도구에 어댑터로 작성하기만 하면 됩니다.

세레나의 도구 및 구성

Serena는 의미론적 코드 검색 도구와 편집 기능, 그리고 셸 실행 기능을 결합합니다. 아래에서 전체 도구 목록을 확인하세요.

일반적으로 모든 도구를 사용하는 것이 좋습니다. 이렇게 하면 Serena가 가장 큰 가치를 제공할 수 있기 때문입니다. 셸 명령(특히 테스트)을 실행해야만 Serena가 자율적으로 실수를 식별하고 수정할 수 있습니다.

하지만 execute_shell_command 도구는 임의 코드 실행을 허용한다는 점에 유의해야 합니다. Serena를 MCP 서버로 사용할 경우, 클라이언트는 일반적으로 도구를 실행하기 전에 사용자에게 권한을 요청하므로, 사용자가 실행 매개변수를 미리 확인한다면 문제가 되지 않습니다. 하지만 문제가 될 수 있으므로 프로젝트의 .yml 구성 파일에서 특정 명령을 비활성화할 수 있습니다. Serena를 코드베이스 수정 없이 코드 분석 및 구현 제안 용도로만 사용하려면 구성에서 편집 도구를 비활성화하는 것을 고려해 볼 수 있습니다.

create_text_file
insert_after_symbol
insert_at_line
insert_before_symbol
replace_symbol_body
delete_lines .

일반적으로 작업 내용을 백업하고 버전 제어 시스템을 사용하여 작업 내용이 손실되는 것을 방지하세요.

다른 코딩 에이전트와의 비교

저희가 아는 바로는 Serena는 모든 기능을 MCP 서버를 통해 사용할 수 있는 최초의 모든 기능을 갖춘 코딩 에이전트로, API 키나 구독이 필요하지 않습니다.

구독 기반 코딩 에이전트

가장 눈에 띄는 구독 기반 코딩 에이전트는 Windsurf, Cursor, VSCode와 같은 IDE에 포함되어 있습니다. Serena의 기능은 Cursor의 Agent, Windsurf의 Cascade, 그리고 곧 출시될 VSCode의 Agent 모드 와 유사합니다.

Serena는 구독이 필요하지 않다는 장점이 있습니다. 하지만 IDE에 직접 통합되어 있지 않아 새로 작성된 코드를 원활하게 검토하기 어렵다는 단점이 있습니다.

더 기술적인 차이점은 다음과 같습니다.

Serena는 특정 IDE에 종속되지 않습니다. Serena의 MCP 서버는 모든 MCP 클라이언트(일부 IDE 포함)와 함께 사용할 수 있으며, Agno 기반 에이전트는 해당 기능을 적용하는 추가적인 방법을 제공합니다.
Serena는 특정 대규모 언어 모델이나 API에 구속되지 않습니다.
Serena는 언어 서버를 사용하여 코드를 탐색하고 편집하므로 코드를 기호적으로 이해할 수 있습니다. IDE 기반 도구는 종종 RAG 기반 또는 순수 텍스트 기반 접근 방식을 사용하는데, 이는 특히 대규모 코드베이스의 경우 성능이 떨어지는 경우가 많습니다.
Serena는 오픈 소스이고 코드베이스가 작기 때문에 쉽게 확장하고 수정할 수 있습니다.

API 기반 코딩 에이전트

구독 기반 에이전트의 대안으로 Claude Code, Cline, Aider, Roo Code 등과 같은 API 기반 에이전트가 있습니다. 이러한 에이전트의 사용 비용은 기본 LLM의 API 비용에 직접 매핑됩니다. 일부 에이전트(예: Cline)는 IDE에 확장 기능으로 포함될 수도 있습니다. 이러한 에이전트는 종종 매우 강력하지만, 주요 단점은 (잠재적으로 매우 높은) API 비용입니다.

Serena 자체는 API 기반 에이전트로 사용할 수 있습니다(위의 Agno 섹션 참조). 아직 Serena용 CLI 도구나 전용 IDE 확장 기능은 개발하지 않았습니다(Serena는 이미 MCP 서버를 지원하는 모든 IDE에서 사용할 수 있으므로, 후자는 필요하지 않을 것으로 예상됩니다). Claude Code처럼 Serena를 CLI 도구로 사용해야 한다는 수요가 있다면, 개발도 고려해 볼 것입니다.

Serena와 다른 API 기반 에이전트의 주요 차이점은 Serena를 MCP 서버로도 사용할 수 있다는 것입니다. 따라서 API 키가 필요 없고 API 비용도 발생하지 않습니다. 이는 Serena만의 고유한 기능입니다.

기타 MCP 기반 코딩 에이전트

DesktopCommander 나 codemcp 처럼 코딩용으로 설계된 다른 MCP 서버도 있습니다. 하지만 저희가 아는 한, 이러한 서버는 의미론적 코드 검색 및 편집 도구를 제공하지 않으며, 순전히 텍스트 기반 분석에만 의존합니다. Serena는 언어 서버와 MCP의 통합을 통해 특히 대규모 코드베이스 환경에서 까다로운 코딩 작업에 매우 강력하고 독보적인 기능을 제공합니다.

온보딩과 기억

기본적으로 Serena는 프로젝트 시작 시 온보딩 프로세스를 진행합니다. 이 프로세스의 목표는 Serena가 프로젝트에 익숙해지고 기억을 저장하여 향후 상호작용에 활용할 수 있도록 하는 것입니다.

메모리는 프로젝트 디렉터리의 .serena/memories/ 에 저장된 파일로, 에이전트가 선택하여 읽을 수 있습니다. 필요에 따라 자유롭게 읽고 수정할 수 있으며, 새 메모리를 직접 추가할 수도 있습니다. .serena/memories/ 디렉터리의 모든 파일은 메모리 파일입니다.

세레나의 사용자 경험이 메모리를 통해 크게 향상되는 것을 확인했습니다. 세레나는 그 자체로 필요할 때마다 새로운 메모리를 생성하도록 설계되었습니다.

다른 MCP 서버와의 결합

MCP 클라이언트를 통해 Serena를 사용할 경우 다른 MCP 서버와 함께 사용할 수 있습니다. 단, 도구 이름 충돌에 주의하세요! 위 정보를 참조하세요.

현재 널리 사용되는 파일 시스템 MCP 서버와 충돌이 발생하고 있습니다. Serena도 파일 시스템 작업을 제공하므로 두 서버를 동시에 활성화할 필요는 거의 없습니다.

Serena 사용에 대한 권장 사항

Serena 커뮤니티가 성장함에 따라 앞으로도 모범 사례를 지속적으로 수집할 예정입니다. Serena를 내부적으로 사용하면서 얻은 교훈을 간략하게 요약해 보겠습니다.

이러한 권장 사항의 대부분은 위에 언급된 모든 에이전트를 포함한 모든 코딩 에이전트에 해당합니다.

어떤 모델을 선택해야 할까?

놀랍게도 Serena는 Claude 3.7의 생각하는 버전(아직 Gemini와의 광범위한 비교는 진행하지 않았습니다)보다 생각하는 버전이 아닌 버전에서 가장 잘 작동하는 것으로 나타났습니다. 생각하는 버전은 시간이 더 오래 걸렸고, 도구 사용에 더 많은 어려움을 겪었으며, 충분한 맥락을 읽지 않고 코드를 작성하는 경우가 많았습니다.

초기 실험에서는 Gemini가 매우 잘 작동하는 것처럼 보였습니다. 아쉽게도 Gemini는 MCP(아직?)를 지원하지 않아서 API 키를 통해서만 사용할 수 있습니다. 다행히 Gemini는 비교적 저렴하고 방대한 컨텍스트를 처리할 수 있습니다.

온보딩

첫 번째 상호작용에서 Serena는 온보딩을 수행하고 첫 번째 메모리 파일을 작성하라는 지시를 받습니다. LLM에 따라 파일이 디스크에 작성되지 않는 경우도 있습니다. 이 경우 Serena에게 메모리를 작성해 달라고 요청하세요.

이 단계에서 Serena는 일반적으로 상당히 많은 텍스트를 읽고 쓰면서 맥락을 채웁니다. 온보딩이 완료되면 토큰이 소진되지 않도록 다른 대화로 전환하는 것이 좋습니다. 온보딩은 명시적으로 트리거하지 않는 한 한 번만 수행됩니다.

온보딩 후에는 메모리를 빠르게 살펴보고, 필요하다면 메모리를 편집하거나 추가 메모리를 추가하는 것이 좋습니다.

코드 편집 전

깨끗한 git 상태에서 코드 생성 작업을 시작하는 것이 가장 좋습니다. 이렇게 하면 변경 사항을 검토하기가 더 쉬워질 뿐만 아니라, 모델 자체도 git diff 명령을 실행하여 변경 사항을 확인하고 스스로 수정하거나 필요한 경우 후속 대화를 통해 작업을 계속할 수 있습니다.

:경고: 중요 : Serena는 시스템 네이티브 줄 끝을 사용하여 파일에 쓰고 git diff를 확인할 수 있으므로 Windows에서 git config core.autocrlf true 로 설정하는 것이 중요합니다. Windows에서 git config core.autocrlf false 로 설정하면 줄 끝 때문에만 큰 diff가 생성될 수 있습니다. 일반적으로 Windows에서 이 git 설정을 활성화하는 것이 좋습니다.

git config --global core.autocrlf true

코드 편집의 잠재적 문제

저희 경험상 LLM은 계산 능력이 매우 부족합니다. 즉, 코드 블록을 적절한 위치에 삽입하는 데 어려움을 겪습니다. 대부분의 편집 작업은 기호 수준에서 수행할 수 있으므로 이 문제를 해결할 수 있습니다. 하지만 때로는 줄 단위 삽입이 유용할 수도 있습니다.

Serena는 편집할 줄 번호와 모든 코드 블록을 다시 한 번 확인하라는 지시를 받았지만, 문제가 발생할 경우 코드 편집 방법을 명시적으로 알려주는 것이 유용할 수도 있습니다.

맥락에서 벗어나다

길고 복잡한 작업이나 Serena가 많은 내용을 읽은 작업의 경우, 컨텍스트 토큰의 한계에 가까워질 수 있습니다. 이 경우 새 대화를 계속하는 것이 좋습니다. Serena는 진행 상황의 현재 상태와 진행을 계속하기 위한 모든 관련 정보를 요약하는 전용 도구를 제공합니다. 이 요약을 생성하고 메모리에 기록하도록 요청할 수 있습니다. 그런 다음 새 대화에서 Serena에게 메모리를 읽고 작업을 계속하도록 요청하면 됩니다. 저희 경험상 이 방법은 매우 효과적이었습니다. 장점은 단일 세션에서는 요약이 필요하지 않기 때문에 Serena가 길을 잃는 경우가 거의 없으며 (내부적으로 요약하는 다른 에이전트와 달리), 올바른 방향으로 가고 있는지 가끔 확인하도록 지시받는다는 것입니다.

게다가 Serena는 맥락을 아껴 쓰도록 지시받았습니다(예: 코드 기호 본문을 불필요하게 읽지 않도록). 하지만 Claude는 항상 아껴 쓰는 데 능숙하지는 않았습니다(Gemini가 더 잘하는 듯했습니다). 필요하지 않다면 본문을 읽지 않도록 명시적으로 지시할 수 있습니다.

도구 실행 제어

Claude Desktop은 도구를 실행하기 전에 사용자에게 묻습니다. 대부분의 도구는 특히 모든 파일이 버전 관리 시스템에 있는 경우 "이 채팅 허용"을 클릭해도 됩니다. 한 가지 예외는 execute_shell_command 도구입니다. 이 도구에서는 각 호출을 개별적으로 검사하는 것이 좋습니다. 이 명령에 대한 각 호출을 검토하고 전체 채팅에 대해 활성화하지 않는 것이 좋습니다.

코드베이스 구조화

Serena는 코드 구조를 사용하여 코드를 찾고, 읽고, 편집합니다. 즉, 잘 구조화된 코드에서는 잘 작동하지만, 완전히 구조화되지 않은 코드(예: 거대하고 모듈화되지 않은 함수를 가진 God-class)에서는 제대로 작동하지 않을 수 있습니다. 타입 주석도 이 부분에서 많은 도움이 됩니다. 코드가 좋을수록 Serena도 더 잘 작동합니다. 따라서 일반적으로 잘 구조화되고 모듈화되며 타입이 지정된 코드를 작성하는 것이 좋습니다. 이는 개발자뿐만 아니라 AI에도 도움이 됩니다 ;).

로깅, 린팅 및 테스트

Serena는 디버깅을 할 수 없습니다(현재 어떤 코딩 어시스턴트도 이를 수행할 수 없는 것으로 알고 있습니다). 따라서 에이전트 루프 내에서 결과를 개선하려면 Serena가 테스트 실행, 스크립트 실행, 린팅(linting) 등을 통해 정보를 수집해야 합니다. 명확한 정보가 포함된 많은 로그 메시지를 포함하고 의미 있는 테스트를 수행하는 것이 매우 유용합니다. 특히 후자는 에이전트가 자체적으로 문제를 해결하는 데 도움이 됩니다.

일반적으로 모든 린팅 검사와 테스트를 통과한 상태에서 편집 작업을 시작하는 것이 좋습니다.

일반적인 조언

특히 간단한 작업일 경우, 실제로 구현하기 전에 작업을 개념화하고 계획하는 데 시간을 투자하는 것이 좋습니다. 이는 더 나은 결과를 얻는 데 도움이 될 뿐만 아니라, 통제력을 높이고 흐름을 따라가는 데도 도움이 됩니다. 한 세션에서는 세레나가 여러분의 코드를 많이 읽어 맥락을 구축할 수 있도록 세부적인 계획을 세운 후, 다른 세션에서는 (적절한 기억을 더듬어 가며) 구현을 계속할 수 있습니다.

문제 해결

Claude Desktop과 다양한 MCP 서버 SDK의 MCP 서버 지원은 비교적 최근에 개발된 기능이므로 불안정할 수 있습니다.

MCP 서버의 작동 구성은 플랫폼과 클라이언트마다 다를 수 있습니다. 상대 경로는 오류의 원인이 될 수 있으므로 항상 절대 경로를 사용하는 것이 좋습니다. 언어 서버는 별도의 하위 프로세스에서 실행되며 asyncio를 통해 호출됩니다. 클라이언트가 충돌을 일으키는 경우가 있습니다. Serena의 로그 창을 활성화했는데 사라지면 무슨 일이 일어났는지 알 수 있습니다.

일부 클라이언트(예: 구스)는 MCP 서버를 제대로 종료하지 못할 수 있으므로, 중단된 파이썬 프로세스를 살펴보고 필요한 경우 수동으로 종료하세요.

세레나 로깅

문제 해결을 돕기 위해 간단한 GUI 로깅 유틸리티를 개발했습니다. 대부분의 고객은 문제 발생 시 프로젝트 설정( myproject.yml )에서 이 유틸리티를 활성화하는 것이 좋습니다. 또한, 많은 고객이 문제 파악에 도움이 되는 MCP 로그를 작성합니다.

로깅 GUI는 일부 클라이언트와 시스템에서 작동하지 않을 수 있습니다. 현재 macOS나 Cline과 같은 VSCode 확장 프로그램에서는 작동하지 않습니다.

감사의 말

우리는 기존의 여러 오픈소스 기술을 기반으로 Serena를 구축했습니다. 가장 중요한 기술은 다음과 같습니다.

multilspy . LSP를 따르는 언어 서버를 감싸는 아름답게 디자인된 래퍼입니다. Serena가 필요로 하는 심볼릭 로직을 구현하여 쉽게 확장할 수 없었기 때문에 종속성으로 통합하는 대신 소스 코드를 복사하여 필요에 맞게 수정했습니다.
파이썬 MCP SDK
Agno 와 관련된 agent-ui 는 Serena가 MCP를 지원하는 모델 외의 모든 모델에서 작업할 수 있도록 하는 데 사용됩니다.
Multilspy를 통해 사용하는 모든 언어 서버입니다.

이러한 프로젝트가 없었다면 세레나는 건설될 수 없었을 것입니다(또는 건설하기가 훨씬 더 어려웠을 것입니다).

세레나 커스터마이징

Serena의 AI 기능을 여러분의 아이디어로 확장하는 것은 매우 쉽습니다. serena.agent.Tool 을 상속하여 새 Tool을 구현하고, apply 메서드(인터페이스의 일부가 아님, Tool 주석 참조)를 구현하기만 하면 됩니다. 기본적으로 SerenaAgent 해당 메서드에 즉시 접근할 수 있습니다.

새로운 언어에 대한 지원을 추가하는 것도 비교적 간단합니다. 커뮤니티에서 어떤 결과물을 내놓을지 기대됩니다! 기여에 대한 자세한 내용은 여기를 참조하세요.

도구 전체 목록

다음은 짧은 설명과 함께 나온 Serena 도구의 전체 목록입니다( uv run serena-list-tools 출력):

activate_project : 프로젝트를 이름으로 활성화합니다.
check_onboarding_performed : 온보딩이 이미 수행되었는지 확인합니다.
create_text_file : 프로젝트 디렉토리에 파일을 생성하거나 덮어씁니다.
delete_lines : 파일 내에서 일정 범위의 줄을 삭제합니다.
delete_memory : Serena의 프로젝트별 메모리 저장소에서 메모리를 삭제합니다.
execute_shell_command : 셸 명령을 실행합니다.
find_referencing_code_snippets : 주어진 위치의 심볼이 참조되는 코드 조각을 찾습니다.
find_referencing_symbols : 지정된 위치의 심볼을 참조하는 심볼을 찾습니다(선택적으로 유형별로 필터링).
find_symbol : 지정된 이름/하위 문자열을 포함하거나 포함하는 심볼에 대한 글로벌(또는 로컬) 검색을 수행합니다(선택적으로 유형으로 필터링).
get_active_project : 현재 활성화된 프로젝트의 이름을 가져오고(있는 경우) 기존 프로젝트를 나열합니다.
get_symbols_overview : 주어진 파일이나 디렉토리에 정의된 최상위 심볼에 대한 개요를 가져옵니다.
insert_after_symbol : 주어진 심볼의 정의가 끝난 뒤에 콘텐츠를 삽입합니다.
insert_at_line : 파일의 주어진 줄에 내용을 삽입합니다.
insert_before_symbol : 주어진 심볼의 정의 시작 부분 앞에 콘텐츠를 삽입합니다.
list_dir : 주어진 디렉토리에 있는 파일과 디렉토리를 나열합니다(선택적으로 재귀 사용 가능).
list_memories : Serena의 프로젝트별 메모리 저장소에 있는 메모리를 나열합니다.
onboarding : 온보딩(프로젝트 구조 및 필수 작업 식별, 예: 테스트 또는 빌드)을 수행합니다.
prepare_for_new_conversation : 새로운 대화를 준비하는 데 필요한 지침을 제공합니다(필요한 맥락을 계속 이해하기 위해).
read_file : 프로젝트 디렉토리 내의 파일을 읽습니다.
read_memory : Serena의 프로젝트별 메모리 저장소에서 지정된 이름의 메모리를 읽습니다.
replace_lines : 파일 내의 특정 줄을 새로운 내용으로 바꿉니다.
replace_symbol_body : 심볼의 전체 정의를 바꿉니다.
restart_language_server : 언어 서버를 다시 시작합니다. Serena를 통하지 않고 편집이 발생할 경우 필요할 수 있습니다.
search_for_pattern : 프로젝트에서 패턴을 검색합니다.
summarize_changes : 코드베이스에 적용된 변경 사항을 요약하기 위한 지침을 제공합니다.
think_about_collected_information : 수집된 정보의 완전성을 고민하기 위한 사고 도구입니다.
think_about_task_adherence : 에이전트가 현재 작업을 여전히 제대로 진행하고 있는지 판단하기 위한 사고 도구입니다.
think_about_whether_you_are_done : 작업이 실제로 완료되었는지 판단하기 위한 사고 도구입니다.
write_memory : Serena의 프로젝트별 메모리 저장소에 지정된 메모리(나중에 참조할 수 있도록)를 씁니다.

Serena

Integrations

데모