Claude Code 및 Codex용 Nette 플러그인

Claude Code와 Codex를 위한 플러그인입니다. 이 플러그인은 모범 사례, 코딩 컨벤션, 자동 파일 유효성 검사를 포함하여 Nette Framework 생태계에 대한 지식을 제공합니다. 두 클라이언트 모두 동일한 스킬(skills), 후크(hooks), 프로젝트 구성을 사용합니다.

설치 (Installation)

Claude Code

먼저, Nette marketplace를 Claude Code에 추가하고(자동 업데이트 활성화):

/plugin marketplace add nette/agent-plugins

다음으로 플러그인을 설치합니다:

/plugin install nette@nette

편집할 때마다 PHP, Latte, NEON, JSON 및 JavaScript 파일에 대한 자동 유효성 검사를 하려면:

/plugin install nette-lint@nette

선택적으로 Nette Framework 기여자들은 다음도 설치할 수 있습니다:

/plugin install nette-dev@nette

자동 PHP 코드 스타일 수정(fixing)을 위해:

/plugin install php-fixer@nette
/php-fixer:install-php-fixer

이 스킬들은 Nette 문서의 관련 페이지와 함께 제공되며, Claude가 세부 정보가 필요할 때 읽습니다. 이 플러그인은 프로젝트 외부에 존재하므로, Claude Code는 파일을 읽을 때 처음으로 권한을 요청합니다. 프롬프트를 건너뛰려면 설정에서 플러그인 디렉터리 읽기를 허용하세요:

{
	"permissions": {
		"allow": ["Read(~/.claude/plugins/cache/nette/**)"]
... 
}

Codex

marketplace를 추가하고 application-development 스킬을 설치합니다:

codex plugin marketplace add nette/agent-plugins
codex plugin add nette@nette

필요한 선택적 플러그인을 모두 설치합니다:

codex plugin add nette-lint@nette
codex plugin add nette-dev@nette
codex plugin add php-fixer@nette

설치 후 새 세션을 시작하세요. php-fixer의 경우, 프로젝트나 전역적으로 사용 가능한지 확인하기 위해 명시적으로 install-php-fixer 스킬을 선택하여 DressCode를 설치해야 합니다.

자동 검증 및 수정(fixing)을 위해 Codex CLI에서 /hooks를 열고 설치된 훅 정의(hook definitions)를 검토하고 신뢰해야 합니다. 플러그인을 단순히 설치하는 것만으로는 해당 훅들을 신뢰할 수 없습니다. 변경된 정의는 별도의 검토가 필요합니다. Codex 훅 설정을 참조하세요.

기존의 .claude-plugin/marketplace.json 및 플러그인 매니페스트(manifests)는 두 클라이언트 모두에서 지원되므로, 별도의 Codex 카탈로그가 필요하지 않습니다. 플러그인 패키징 호환성을 참조하세요.

요구 사항 및 편집 범위

Skills는 PHP 설치가 필요 없습니다. 훅은 PATH에 PHP 8.0 이상과 아래 나열된 관련 프로젝트 도구를 필요로 합니다. DressCode는 PHP 8.4 이상이 필요합니다.

훅은 Claude Code의 Edit/Write 및 Codex의 apply_patch 호출 후에 실행됩니다. Codex 패치는 여러 파일을 변경할 수 있습니다: 일치하는 각 파일이 검사되고, 이름이 변경된 파일은 목적지에서 검사되며, 삭제된 파일은 건너뜁니다. 셸 명령어(shell commands)나 다른 도구를 통해 이루어진 변경 사항은 이러한 훅을 트리거하지 않으므로, 해당 편집에 대해서는 적절한 프로젝트 검사를 명시적으로 실행해야 합니다.

로컬 마켓플레이스 설치는 Windows에서 Codex CLI 0.156.1을 사용하여 검증되었습니다. 이전 버전의 Codex 및 호스팅 환경은 이 검증 범위에 포함되지 않습니다. 훅 스크립트와 그 도구들은 클라이언트의 실행 환경에 존재해야 합니다.

플러그인

nette – 애플리케이션 개발자를 위한 플러그인

Nette Framework를 사용한 애플리케이션 구축을 위한 모범 사례 및 관례 — Nette 개발의 모든 주요 영역을 포괄하는 광범위한 기술 세트입니다.

nette-lint – 자동 검증

지원되는 편집 후에 파일을 검증하고 오류를 어시스턴트에게 직접 보고합니다:

nette-dev – 프레임워크 기여자용

Nette Framework 자체에 기여하기 위한 코딩 표준 및 관례입니다.

php-fixer – 자동 PHP 스타일 수정

지원되는 편집 후 DressCode를 사용하여 PHP 코드 스타일을 자동으로 수정하는 선택적 플러그인입니다: 프로젝트의 dresscode.neon이 있는 경우 이를 따르고, 그렇지 않은 경우에는 Nette 코딩 표준을 따릅니다.

설정 (Configuration)

이 플러그인들의 프로젝트 수준 동작은 프로젝트 내의 .nette-claude.json 파일을 통해 구성되며, 이 파일은 오직 플러그인 자체의 훅에 의해서만 읽힙니다. 동일한 파일이 Claude Code와 Codex 모두에 적용됩니다. 호환성을 위해 이름이 유지됩니다. 이는 편집된 파일로부터 상위 디렉터리를 검색합니다(예: .gitignore). 따라서 모노레포에서는 각 패키지가 자신만의 설정을 가질 수 있습니다.

훅에서 파일을 제외하기 (Excluding files from hooks)

특정 경로(일반적으로 의도적으로 깨진 템플릿을 포함하는 fixtures 폴더, NEON 또는 PHP)를 제외하려면, 해당 훅에 exclude 목록을 제공하십시오. 각 최상위 키는 훅 이름입니다:

사용 가능한 훅(hooks): lint-php (.php/.phpt), lint-latte (.latte), lint-neon (.neon), lint-json (.json/.jsonc), lint-js (.js/.ts).

php-fixer의 PHP 수정기(fixer)는 여기에 구성되지 않았습니다: 프로젝트의 dresscode.neon을 따르며, 여기에는 excludePaths가 포함됩니다. 또한, 프로젝트에 Nette 코딩 표준이 없는 경우 Nette 코딩 표준을 사용합니다.

lint-json은 .jsonc, tsconfig*.json, jsconfig*.json, devcontainer.json 및 .vscode/ 아래의 모든 파일을 JSONC(주석 및 꼬리 쉼표 허용)로 처리합니다. 추가 파일을 JSONC로 지정하려면 동일한 gitignore 스타일 패턴을 가진 jsonc 목록을 추가하십시오:

{
	"lint-json": {
		"jsonc": ["config/*.json"]
	}
...

패턴 의미론(gitignore와 유사), .nette-claude.json이 포함된 디렉토리를 기준으로 해석됩니다:

• 슬래시가 없는 패턴 (fixtures, fixtures*)은 모든 깊이에서 해당 이름의 경로 세그먼트를 일치시킵니다;
• 슬래시가 있는 패턴 (tests/**/broken)은 설정 디렉토리에 고정된(anchored) glob입니다;
• *는 단일 세그먼트 내에서 일치하며, **는 디렉토리를 가로지릅니다;
• 디렉토리를 일치시키면 그 내용을 제외하는 효과도 있습니다.

사용법 (Usage)

기술(Skills)은 대화 컨텍스트에 따라 자동으로 활성화됩니다. 예를 들면: