synaptiai/prompt-decorators

Prompt Decorators는 거대 언어 모델 (LLMs)을 위한 프롬프트가 강화되고, 구조화되며, 변환되는 방식을 표준화하는 포괄적인 프레임워크입니다. 이 저장소에는 공식 Prompt Decorators 명세 (Specification)와 그 완전한 Python 참조 구현체가 모두 포함되어 있습니다.

Prompt Decorators는 소프트웨어 디자인 패턴에서 영감을 받은 표준화된 어노테이션 (annotation) 시스템을 도입하여, 사용자가 단순하고 조합 가능한 "데코레이터 (decorators)"를 통해 LLM의 동작을 수정할 수 있도록 합니다. 프롬프트에 +++Reasoning

, +++StepByStep

, 또는 +++OutputFormat

와 같은 어노테이션을 접두사로 붙임으로써, 사용자는 서로 다른 플랫폼과 구현체에 걸쳐 AI 모델이 요청을 처리하고 응답하는 방식을 일관되게 제어할 수 있습니다.

이 프로젝트는 다음과 같은 기능을 제공함으로써 점점 복잡해지는 AI 상호작용 문제를 해결합니다:

명세 (The Specification): 데코레이터 구문, 동작 및 확장 메커니즘을 정의하는 공식 표준
Python 구현체 (The Python Implementation): 포괄적인 툴링을 갖춘 프로덕션 준비 완료된 참조 구현체
MCP 통합 (MCP Integration): Claude Desktop과 같은 도구에서 프롬프트 데코레이터 기능을 활성화하는 모델 컨텍스트 프로토콜 (Model Context Protocol) 서버

📝 명세 (Specification): 표준을 정의하는 공식 Prompt Decorators 명세 (v1.0)
🛠️ 핵심 프레임워크 (Core Framework): 레지스트리 기반 데코레이터 관리를 지원하는 Python 구현체
🧩 140개 이상의 데코레이터 (140+ Decorators): 추론, 포맷팅 등을 다루는 포괄적인 사전 구축 데코레이터 라이브러리
🔌 MCP 서버 (MCP Server): 데스크톱 AI 애플리케이션에서 사용할 수 있도록 모델 컨텍스트 프로토콜 (Model Context Protocol)과 통합
🧷 Claude Code 플러그인 (Claude Code Plugin): 인라인 ::Name(params) 식별자 (sigils)를 모델이 프롬프트를 보기 전에 정밀한 지침으로 확장하는 드롭인 Claude Code 플러그인. /decorate 슬래시 명령, 상시 활성화 설정, 그리고 선택적 사용이 가능한 Haiku 기반 자동 선택기 (auto-selector)를 제공합니다.
📚 광범위한 문서 (Extensive Documentation): 사용자와 개발자 모두를 위한 API 참조, 가이드 및 예제

대규모 언어 모델 (LLM)이 산업 전반의 워크플로우에 점점 더 통합됨에 따라, 이러한 시스템과 상호작용하기 위한 표준화되고 일관된 방식의 필요성이 분명해지고 있습니다. 현재의 프롬프트 엔지니어링 (Prompt Engineering) 접근 방식은 대체로 임시방편적(ad-hoc)이며, 시스템이나 사용 사례를 전환할 때 광범위한 문서화, 재발명, 그리고 상당한 인지적 부하 (Cognitive Overhead)를 요구합니다.

Prompt Decorators는 단순하고 조합 가능한 어노테이션 (Annotations)을 통해 AI의 동작을 수정하는 체계적인 접근 방식을 제공함으로써 이 과제를 해결합니다. 프로그래밍의 데코레이터 패턴 (Decorator pattern)과 Python의 함수 데코레이터 (Function decorators)에서 영감을 받은 이 방식은, 핵심 프롬프트와 응답을 처리하고 제시하는 방법에 대한 지침을 분리하는 추상화 계층 역할을 합니다.

현재의 프롬프트 엔지니어링은 다음과 같은 몇 가지 한계점을 겪고 있습니다:

불일치 (Inconsistency): 사용자, 플랫폼 및 모델 간에 지침이 크게 다름
장황함 (Verbosity): 상세한 지침이 콘텐츠에 사용될 수 있는 토큰 컨텍스트 (Token context)를 소비함
인지적 부하 (Cognitive Overhead): 사용자가 특정 프롬프팅 기술을 기억하거나 문서화해야 함
조합성 부족 (Lack of Composability): 서로 다른 지침 패러다임을 결합하는 것이 번거로움
문서화되지 않은 동작 (Undocumented Behavior): 기대되는 모델 동작이 명시적이기보다 암시적인 경우가 많음

Prompt Decorators는 프롬프트 엔지니어링의 핵심 과제들을 해결합니다:

불일치 (Inconsistency): 다양한 LLM 플랫폼 전반에 걸쳐 표준화된 구문과 동작을 제공함
장황함 (Verbosity): 긴 지침을 간결한 어노테이션으로 대체함
인지적 부하 (Cognitive Overhead): 재사용 가능한 패턴을 통해 프롬프트 작성을 단순화함
조합성 부족 (Lack of Composability): 여러 지침 패러다임의 깔끔한 결합을 가능하게 함
문서화되지 않은 동작 (Undocumented Behavior): 기대되는 모델 응답을 명시적으로 정의함

특정 추론 패턴을 위한 프롬프트를 작성하든, 특정 형식으로 출력을 구조화하든, 또는 서로 다른 모델 간에 일관된 응답을 보장하든, Prompt Decorators는 프롬프트 엔지니어링을 더욱 모듈화되고, 재사용 가능하며, 유지보수 가능하게 만드는 체계적인 접근 방식을 제공합니다.

Prompt Decorators 프레임워크는 다음과 같은 방식을 통해 이러한 과제들을 해결합니다:

표준화 (Standardization): 플랫폼과 모델 전반에 걸친 공통 어휘 및 구문
효율성 (Efficiency): 토큰 소비를 줄이는 간결한 어노테이션 (annotations)
재사용성 (Reusability): 다양한 컨텍스트에서 재사용할 수 있는 일관된 동작
조합 가능성 (Composability): 복잡한 상호작용 패턴을 위해 데코레이터 (decorators)를 결합할 수 있는 능력
명시적 동작 (Explicit Behavior): 기대되는 모델 응답에 대한 명확한 문서화
인지 부하 감소 (Reduced Cognitive Load): 긴 지시문 대신 간단한 어노테이션 사용

📚 레지스트리 기반 데코레이터 관리 (Registry-based decorator management): 메타데이터를 포함한 데코레이터의 중앙 집중식 레지스트리
✅ 파라미터 검증 및 타입 체크 (Parameter validation and type checking): 데코레이터 파라미터에 대한 강력한 검증
🔢 데코레이터 버전 관리 (Decorator versioning): 데코레이터의 유의적 버전 관리 (semantic versioning) 지원
🔄 호환성 확인 (Compatibility checking): 데코레이터 간의 호환성 검증
📝 문서 생성 (Documentation generation): 데코레이터를 위한 문서 자동 생성
🧩 동적 로딩 (Dynamic loading): 정의 파일로부터의 런타임 (runtime) 데코레이터 로딩
🔍 런타임 데코레이터 탐색 (Runtime decorator discovery): 데코레이터의 동적 탐색 및 등록

Prompt Decorators 프로젝트는 현재 활발히 개발 중입니다.

데모를 테스트하거나 Claude Desktop과 함께 MCP 서버 구현을 실행하여 프롬프트 데코레이터가 어떻게 작동하는지 확인할 수 있습니다.

또는 이 저장소의 .cursorrules를 Cursor (또는 ChatGPT/Claude)의 시스템 지침 (system instructions)으로 사용하여 모델을 지시할 수 있습니다. 직접 사용해 보시고 경험을 공유해 주세요!

✅ 핵심 데코레이터 레지스트리 (Core Decorator Registry): 표준화된 JSON 정의로부터 데코레이터를 로드합니다.
✅ 데코레이터 적용 (Decorator Application): 매개변수 검증 (parameter validation)과 함께 프롬프트에 데코레이터를 적용합니다.
✅ 정교한 변환 (Sophisticated Transformation): 데코레이터 매개변수를 프롬프트 조정 사항으로 변환합니다.
✅ 다양한 입력 형식 (Multiple Input Formats): Python 함수, 문자열(strings), JSON을 지원합니다.
✅ 매개변수 검증 및 타입 체크 (Parameter validation and type checking): 데코레이터 매개변수에 대한 강력한 검증을 수행합니다.
✅ 표준 데코레이터 (Standard Decorators): 명세서(specification)에 정의된 표준 데코레이터를 구현합니다.
✅ 확장 프레임워크 (Extension Framework): 도메인 특화 데코레이터 확장을 지원합니다.
✅ 문서 생성 (Documentation Generation): 데코레이터 정의로부터 자동화된 문서 생성을 지원합니다.

구현 상태에 대한 자세한 분석은 구현 상태 (Implementation Status) 문서를 참조하세요.

이 프로젝트의 로드맵은 ROADMAP 파일에 설명되어 있습니다.

PyPI에서 패키지를 설치할 수 있습니다: https://pypi.org/project/prompt-decorators/

pip install prompt-decorators

추가 기능을 위해 선택적 의존성 (optional dependencies)을 설치할 수 있습니다:

# Model Context Protocol (MCP) 통합을 위해
pip install "prompt-decorators[mcp]"
# 개발 및 테스트를 위해
...

import prompt_decorators as pd
# 사용 가능한 데코레이터 로드
pd.load_decorator_definitions()
...

설치 후, 모든 것이 올바르게 작동하는지 확인하세요:

# 패키지 설치 확인
python -c "import prompt_decorators; print(prompt_decorators.__version__)"
# 레지스트리 로딩 확인
...

로드된 데코레이터 개수와 함께 "Registry verification successful"라는 메시지가 보인다면, 시작할 준비가 된 것입니다!

더 자세한 예시와 사용법은 공식 문서를 참조해 주세요.

이 프로젝트는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

기여를 환영합니다! 이 프로젝트에 기여하는 방법에 대한 가이드라인은 CONTRIBUTING 파일을 읽어주세요.

이 프로젝트는 다음 개인 및 조직의 기여 없이는 불가능했을 것입니다:

Mostapha Kalami Heris: 이 사양(specification)과 저장소(repository)에 영감을 준 논문 "Prompt Decorators: A Simple Way to Improve AI Responses"를 작성해 주셨습니다.
Synaptiai: 이 프레임워크와 사양(specification)의 제작자이자 유지 관리자입니다.
Contributors: 이 프로젝트에 기여해 주신 모든 멋진 분들입니다.