# Maguyva의 PowerShell 지원: 스크립트와 모듈을 위한 코드 그래프

Canonical source: https://maguyva.ai/ko/languages/powershell

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Maguyva는 AST, 심볼, 그래프로 PowerShell을 지원하여, AI 에이전트가 스크립트와 모듈 전반에서 함수, 클래스, cmdlet 호출을 따라갈 수 있게 합니다.

## 지원 현황 요약

- 등급: AST 및 심볼 지원
- 셸
- 확장자: .ps1, .psd1, .psm1
- 구문 인식 검색과 구조적 컨텍스트를 위한 실제 AST 파싱을 제공합니다.
- 이름이 지정된 심볼은 시맨틱 조회와 상호 참조에 활용됩니다. 관계 추출이 활성화된 경우 그래프 내비게이션을 사용할 수 있습니다.
- 이 언어는 그래프 인식 검색에 심볼과 관계를 제공합니다. 지원되는 에지 유형은 언어 고유의 구문 구조에 따라 다릅니다.
- AST 파싱과 심볼 추출을 모두 지원합니다.

## 가장 적합한 경우

- 스크립트끼리 서로의 함수를 호출하는 대규모 `.ps1`, `.psm1` 자산을 가진 인프라 및 운영 팀.
- 고급 함수, 클래스, 열거형으로 구성된 PowerShell 모듈.
- 변경 전에 어떤 스크립트가 서비스, 파일 공유, 레지스트리 키를 건드리는지 에이전트가 확인해야 하는 자동화 런북.

## 에이전트 워크플로

- 고급 함수의 매개변수를 바꾸기 전에 모든 호출자를 찾습니다.
- 런북을 바꾸기 전에 `Restart-Service` 같은 cmdlet을 호출하는 스크립트를 나열합니다.
- 모듈을 리팩터링하기 전에 공유 변수에 쓰는 함수를 매핑합니다.

## PowerShell이 얕은 AI 도구를 넘어뜨리는 지점

여러분의 함수와 기본 제공 cmdlet은 같은 이름 짓기 스타일을 씁니다. `Get-Invoice`와 `Get-ChildItem`는 똑같아 보이므로, 동사를 기준으로 "기본 제공" 명령을 걸러 내는 도구는 여러분의 함수까지 버리게 됩니다. 스크립트는 모듈 수준 코드, 함수, 클래스, 스크립트 블록을 한 파일에 섞어 두기 때문에, 어떤 줄이 어느 함수에 속하는지 알기도 어렵습니다.

Maguyva는 두 종류의 호출을 모두 유지하고, 각 호출을 그것이 들어 있는 함수에 귀속합니다.

## Maguyva가 PowerShell에서 추출하는 것

Maguyva는 `.ps1`, `.psm1`, `.psd1` 파일을 지원합니다. 함수와 클래스 메서드는 호출 가능 항목으로, 클래스와 열거형은 타입으로 추출됩니다. 스크립트 매개변수와 메서드 매개변수가 추적되며, 함수 안의 읽기와 쓰기는 모듈이 아니라 그 함수에 귀속됩니다.

cmdlet 호출은 그래프에 남습니다. PowerShell에는 대부분의 언어가 쓰는 표준 라이브러리 필터가 적용되지 않으므로, `Write-Host`, `Get-ChildItem`, `Restart-Service`는 여러분의 `Get-*`, `Set-*` 함수 옆에 호출 엣지로 나타납니다. 에이전트는 어떤 스크립트가 서비스를 다시 시작하는지, 어떤 함수가 콘솔에 쓰는지 물어 구조에 기반한 답을 얻을 수 있습니다.

PowerShell에서는 적용 대상 아님으로 표시된 관계 유형이 없으므로, 그래프에는 클래스 상속과 인터페이스 구현, 인스턴스화, 제어 흐름, 읽기와 쓰기도 기록됩니다.

## 에이전트 프롬프트 예시

- "`Invoke-Backup`를 누가 호출하고, 어떤 예약 스크립트에서 호출하나요?" (`find_symbol`, 그다음 `dependency_search` incoming)
- "`Restart-Service`를 호출하는 함수는 무엇인가요?" (`dependency_search`)
- "`Deploy-Site`가 처음부터 끝까지 무엇을 하는지 추적해 줘." (`get_task_context`)

## 알려진 한계

- cmdlet 호출이 유지되므로, `Write-Host`나 `Select-Object`처럼 아주 흔한 호출에는 들어오는 엣지가 매우 많습니다. 범위를 좁힌 호출 그래프가 필요하면 여러분의 함수에서 시작하세요.
- `Import-Module`와 도트 소싱은 일반 명령이므로, `structural_search`의 `imports` 프리셋은 아무것도 선택하지 않습니다. 목록을 보려면 `text_pattern_search`를 사용하세요.

## 다음 단계

[빠른 시작](/ko/docs/quickstart)으로 저장소를 연결한 다음, [호환성 페이지](/ko/docs/compatibility)에서 지원 매트릭스를 확인하세요. 스크립트가 호출하는 .NET 코드라면 [C# 가이드](/ko/languages/csharp)를 읽어 보세요.

## 엔진 세부 정보

- PowerShell 지원은 `.ps1`, `.psm1`, `.psd1`을 다룹니다. 함수와 클래스 메서드는 호출 가능 항목이고, 클래스와 열거형은 타입입니다.
- PowerShell에서는 표준 라이브러리 필터가 꺼져 있으므로, `Get-ChildItem` 같은 cmdlet 호출이 여러분의 함수와 함께 그래프에 남습니다.
- 함수 안의 읽기와 쓰기는 모듈이 아니라 그 함수에 귀속됩니다.

## 유용한 MCP 진입점

- `find_symbol`: 고급 함수나 클래스의 정의와 호출자가 필요할 때 사용하세요.
- `dependency_search`: `Restart-Service` 같은 cmdlet에 incoming 탐색을 사용해 그것을 호출하는 스크립트를 확인하세요.
- `get_task_context`: "`Deploy-Site`가 처음부터 끝까지 무엇을 하는지 추적해 줘" 같은 프롬프트에 사용하세요.