shellcheck-configuration

shellcheck-configuration 스킬 개요

shellcheck-configuration 스킬이 하는 일

shellcheck-configuration 스킬은 에이전트가 실제 셸 스크립트 품질 관리에 맞게 ShellCheck를 설정하고, 결과를 해석하며, 운영에 맞게 튜닝하도록 돕습니다. 단순히 “린터를 실행한다” 수준을 넘어서, 저장소 단위 설정, CI 게이팅, 대상 셸 선택, 경고 억제 전략, 그리고 이식성을 해치지 않으면서 발견 항목을 고치는 방법까지 필요할 때 특히 유용합니다.

shellcheck-configuration를 써야 하는 사람

이 스킬은 다음과 같은 경우에 잘 맞습니다:

• 저장소에 처음으로 ShellCheck를 도입하는 개발자
• CI나 코드 리뷰에서 셸 린팅 기준을 통일하려는 팀
• 기존 bash, sh, dash, ksh 스크립트를 정리하는 유지보수 담당자
• 즉흥적인 코멘트 대신 일관된 린트 기준을 원한는 리뷰어

주요 필요가 “경고 코드 하나를 설명해 달라” 정도라면 일반 프롬프트만으로도 충분할 수 있습니다. 하지만 반복 가능한 설정과 정책이 필요하다면 shellcheck-configuration skill이 더 적합합니다.

실제로 해결하려는 일

사용자가 보통 원하는 결과는 다음 네 가지 중 하나입니다:

1. 자신의 플랫폼에 맞게 ShellCheck를 올바르게 설치한다
2. 적절한 셸 대상과 규칙 허용 범위로 설정한다
3. CI 또는 머지 전 검사에 통합한다
4. 시끄럽기만 한 린트 출력을 실제로 조치 가능한 수정 항목과 리뷰 기준으로 바꾼다

이 스킬은 도구 설정과 의사결정이 함께 필요한 목표에서 가장 강합니다.

일반 프롬프트와 다른 점

일반 프롬프트도 “ShellCheck를 써라” 정도의 조언은 할 수 있습니다. 하지만 shellcheck-configuration 스킬은 다음처럼 구조화된 도움이 필요할 때 훨씬 유용합니다:

• 대상 셸을 고르고 그에 맞는 옵션을 선택하기
• 무엇을 suppress하고 무엇을 강제할지 결정하기
• 저장소 현실에 맞는 .shellcheckrc 정책 만들기
• false positive를 유지보수 가능한 방식으로 처리하기
• ShellCheck를 로컬 린트 실행용이 아니라 Code Review용으로 활용하기

도입 전에 알아둘 제약

이 스킬은 자동화 중심이라기보다 가이드 중심입니다. 저장소를 보면 helper script나 패키지 리소스 없이 SKILL.md 하나만 있으므로, 저장소 맞춤형 턴키 명령보다 강한 설명과 예시를 기대하는 편이 맞습니다. 실제 셸 파일, 현재 에러, CI 맥락을 함께 제공할수록 결과가 좋아집니다.

shellcheck-configuration 스킬 사용 방법

shellcheck-configuration 설치 맥락

먼저 다음 명령으로 에이전트 환경에 스킬을 설치합니다:

npx skills add https://github.com/wshobson/agents --skill shellcheck-configuration

그다음 실제 분석이 수행될 환경에 ShellCheck 자체가 설치되어 있어야 합니다:

# macOS
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# Verify
shellcheck --version

이 스킬은 설정과 사용법을 도와주지만, shellcheck 바이너리 자체를 대신하지는 않습니다.

가장 먼저 읽어야 할 파일

다음 파일부터 보세요:

• plugins/shell-scripting/skills/shellcheck-configuration/SKILL.md

이 스킬에는 별도의 README.md, 규칙 파일, helper script가 없기 때문에, 실무적으로 필요한 안내가 거의 전부 여기에 모여 있습니다. 저장소 전체를 보고 기능을 추정하기 전에 이 파일을 먼저 읽는 것이 좋습니다.

실무에서 잘 맞는 사용 사례

다음이 필요할 때 shellcheck-configuration usage가 특히 유용합니다:

• 프로젝트용 .shellcheckrc를 새로 만들거나 다듬기
• 엄격한 강제 적용과 점진적 도입 사이에서 결정하기
• 여러 스크립트에 반복해서 나타나는 경고 패턴 고치기
• ShellCheck를 CI/CD 파이프라인에 연결하기
• 셸 변경이 포함된 pull request를 리뷰하기
• inline disable이 허용 가능한지 판단하기

스킬이 제대로 작동하려면 필요한 입력

그냥 “ShellCheck 설정해 줘”라고 하기보다 구체적인 입력을 주세요. 좋은 입력은 다음과 같습니다:

• 대상 셸: bash, sh, dash, ksh
• 샘플 스크립트 또는 저장소 경로
• 현재 shellcheck 출력
• 코드가 CI, 컨테이너, 여러 배포판에서 실행되는지 여부
• 팀 정책: warning에서도 실패할지, error만 실패할지, advisory로만 둘지
• POSIX sh 이식성이 중요한지 여부

이런 맥락이 없으면 스킬도 결국 일반적인 권고만 할 수 있습니다.

막연한 목표를 강한 프롬프트로 바꾸기

약한 프롬프트:

• “Help me use ShellCheck.”

강한 프롬프트:

• “Use the shellcheck-configuration skill to propose a .shellcheckrc for a repo with mostly bash scripts, a few POSIX sh entrypoints, CI on Ubuntu, and a goal of blocking high-confidence issues while allowing justified inline suppressions. Explain each config choice and how it affects code review.”

이 프롬프트가 잘 작동하는 이유:

• 어떤 셸들이 섞여 있는지 명시한다
• 강제 수준을 정의한다
• 환경 제약을 알려준다
• 파일만 던져 달라는 게 아니라 근거 설명까지 요구한다

Code Review를 위한 shellcheck-configuration 예시 프롬프트

다음과 같은 프롬프트를 사용할 수 있습니다:

Use the shellcheck-configuration skill for Code Review. Review this shell script diff, identify the ShellCheck issues most likely to matter in production, separate correctness bugs from style issues, and recommend whether to fix, suppress, or ignore each one. Assume the repo standard is Bash in CI but portability matters for small utility scripts.

이 방식은 단순히 “이 스크립트 리뷰해 줘”라고 하는 것보다 더 좋은 결과를 줍니다. 이슈를 분류하고 정책에 맞춰 판단하라고 명확히 요청하기 때문입니다.

설치부터 강제 적용까지 권장 워크플로

1. ShellCheck를 설치합니다.
2. 셸 대상과 저장소 목표를 함께 주고 shellcheck-configuration 스킬을 호출합니다.
3. .shellcheckrc를 생성하거나 다듬습니다.
4. 먼저 대표적인 스크립트들에 shellcheck를 실행합니다.
5. CI에서 강제하기 전에 신호 대비 잡음이 좋은 경고부터 수정합니다.
6. 정당한 예외에 대한 suppression 정책을 정합니다.
7. 경고량이 관리 가능한 수준이 된 뒤에만 CI 또는 pre-commit 통합을 추가합니다.

이 순서를 따르면 팀이 정책 합의도 하기 전에 린트 게이트부터 켜 버리는 흔한 실패를 줄일 수 있습니다.

기존 lint 출력과 함께 스킬 쓰기

이미 shellcheck를 실행했다면 다음을 함께 붙여 주세요:

• SC2086, SC2046, SC2155 같은 경고 코드
• 해당 라인
• 그 이슈가 의도된 것인지 여부
• 스크립트 shebang에 선언된 셸

특히 다음 중 무엇에 해당하는지 판단이 필요할 때 이 스킬의 가치가 큽니다:

• 실제 버그
• 이식성 리스크
• 스타일 선호
• suppress할 만한 false positive

가장 중요한 설정 결정 포인트

대개 영향이 큰 선택은 다음입니다:

• 대상 셸을 정확히 맞추는 것
• 프로젝트 단위 .shellcheckrc를 사용할지 여부
• 전역 ignore보다 inline disable을 언제 우선할지
• CI가 모든 발견 항목에서 실패해야 하는지, 일부만 실패해야 하는지
• 기존 레거시 코드를 어느 정도까지 예외로 둘지

이 결정들은 개별 경고 하나를 고치는 것보다 도구에 대한 신뢰에 훨씬 큰 영향을 줍니다.

결과 품질을 높이는 실전 팁

스킬에 다음 산출물을 요청해 보세요:

• 초안 .shellcheckrc
• 예시가 포함된 suppression 정책
• CI 명령 예시
• 경고의 “지금 고칠 것 vs 나중에 고칠 것” 분류
• 반복되는 발견 항목에 대한 코드 리뷰 가이드

이렇게 요청하는 편이 ShellCheck 이론만 묻는 것보다 훨씬 실용적입니다. 이 스킬에는 기본 개념도 들어 있지만, 진짜 가치는 그것을 저장소 정책으로 바꿔 주는 데 있습니다.

shellcheck-configuration 스킬 FAQ

shellcheck-configuration는 초보자에게도 괜찮을까?

그렇습니다. 실제로 셸 스크립트를 다루고 있다면 초보자에게도 도움이 됩니다. 이 스킬에는 ShellCheck의 기본 개념과 설치 안내가 포함되어 있어 시작점으로 쓰기 좋습니다. 다만 실제 스크립트와 실제 경고를 함께 놓고 사용할 때 가치가 가장 큽니다.

이미 ShellCheck를 아는데도 shellcheck-configuration 스킬이 필요할까?

그럴 수 있습니다. 경고 카탈로그와 커맨드라인 기초를 이미 알고 있더라도, 저장소 전반의 설정, CI 정책, suppression 전략, ShellCheck 기반 리뷰 워크플로를 정리하는 데는 여전히 유용합니다.

자동화 스크립트나 바로 쓸 수 있는 CI 템플릿도 들어 있나?

이 스킬에서 그런 근거는 뚜렷하지 않습니다. 저장소 신호상 SKILL.md만 확인되므로, 번들 스크립트나 재사용 가능한 템플릿보다는 개념적 가이드와 예시를 기대하는 편이 맞습니다.

언제 shellcheck-configuration를 쓰지 않는 게 좋을까?

다음 경우라면 굳이 쓸 필요가 없습니다:

• shellcheck file.sh를 한 번만 실행하면 되는 경우
• 문제가 정적 분석 정책과 무관한 경우
• 자동 수정기를 원하는 경우; ShellCheck는 주로 문제를 보고하지 코드를 재작성하진 않습니다
• 팀이 이미 설정을 확정했고 명령어 레퍼런스만 필요한 경우

일반 프롬프팅과는 어떻게 다른가?

일반 프롬프팅도 경고 설명은 할 수 있지만, 저장소 단위 의사결정은 자주 놓칩니다. 예를 들어 대상 셸, suppression 경계, 도입 순서, 코드 리뷰 기준 같은 부분입니다. shellcheck-configuration guide는 일회성 답변보다 반복 가능한 린팅 접근 방식이 필요할 때 더 적합합니다.

shellcheck-configuration는 여러 셸이 섞인 저장소에도 적합한가?

네, 다만 어떤 셸이 섞여 있는지 반드시 알려줘야 합니다. bash와 POSIX sh 스크립트가 함께 있는 저장소는 범위를 명확히 나누지 않으면, 권고가 한쪽 셸에 과하게 맞춰져 다른 쪽에는 잡음만 늘릴 수 있습니다.

shellcheck-configuration 스킬 개선 방법

실제 셸 환경을 구체적으로 알려주기

shellcheck-configuration 결과를 가장 빨리 개선하는 방법은 다음을 분명히 적는 것입니다:

• 스크립트 그룹별 셸 방언
• OS 또는 CI 러너
• 스크립트가 source되는지 직접 실행되는지
• 이식성이 필요한지 여부

ShellCheck 권고는 셸 의미론에 크게 좌우됩니다. 입력이 모호하면 조언도 과하게 넓고 뭉뚱그려질 수밖에 없습니다.

요약 말고 실제 파일 제공하기

“셸 스크립트가 좀 있다”라고만 하지 말고, 다음을 주세요:

• 대표 스크립트 하나
• 현재 .shellcheckrc가 있다면 그 내용
• 현재 경고 코드 몇 개
• 지금 린팅을 돌리는 CI 스니펫

이렇게 해야 스킬이 일반적인 베스트 프랙티스에서 멈추지 않고 실제 설정 조언으로 넘어갈 수 있습니다.

문법이 아니라 정책을 요청하기

더 강한 요청:

• “draft a .shellcheckrc and explain what the team should enforce”

더 약한 요청:

• “show shellcheck config options”

사용자에게 중요한 것은 플래그를 외우는 일이 아니라 무엇을 표준으로 삼을지 결정하는 일입니다. 유지 가능한 정책을 고르도록 스킬에 요청하세요.

흔한 실패 패턴 주의하기

결과가 부실해지는 대표적인 경우는 다음과 같습니다:

• bash와 sh를 구분해 주지 않는 경우
• 경고가 많은 레거시 저장소에 곧바로 zero-warning 강제를 요구하는 경우
• 경고를 이해하기 전에 전역 suppress부터 해 버리는 경우
• 모든 발견 항목을 똑같이 심각하게 취급하는 경우
• 코드 리뷰 워크플로를 무시하고 로컬 실행만 보는 경우

이 스킬은 단순 나열보다 우선순위 정리에 쓸 때 가장 도움이 됩니다.

Code Review 워크플로에 맞게 shellcheck-configuration 개선하기

리뷰 용도로 쓸 때는 발견 항목을 다음 범주로 나눠 달라고 요청하세요:

• correctness
• quoting and expansion safety
• portability
• maintainability
• style-only

이렇게 하면 위험한 셸 패턴은 놓치지 않으면서도, 가치가 낮은 스타일 이슈 때문에 머지를 막는 일을 줄일 수 있습니다.

첫 출력 이후 반드시 한 번 더 다듬기

첫 응답을 받은 뒤에는 다음처럼 후속 요청을 하세요:

• “tighten this config for CI”
• “make this safer for POSIX portability”
• “reduce false positives for sourced helper files”
• “which suppressions should stay inline rather than in .shellcheckrc?”

첫 번째 응답은 방향을 잡는 용도이고, 두 번째부터가 실제 강제 수준을 맞추는 단계라고 보는 편이 좋습니다.

스킬로 도입 단계를 나눠서 진행하기

대형 레거시 저장소라면 다음 세 단계를 요청해 보세요:

1. 기본 advisory 설정
2. 우선순위가 매겨진 수정 목록
3. 더 엄격한 미래 목표 설정

이런 단계적 접근은 처음부터 hard-fail 린팅을 켜서 개발자 반발을 크게 만드는 것보다 대개 더 효과적입니다.

실제 ShellCheck 출력과 권고를 대조하기

가장 좋은 검증 루프는 단순합니다:

1. 스킬에 설정과 정책을 요청한다
2. shellcheck를 실행한다
3. 나온 경고 구성을 확인한다
4. 그 결과를 다시 스킬에 넣어 조정한다

이 과정을 거치면 shellcheck-configuration skill은 정적인 안내문이 아니라 실제 도입과 운영을 밀어주는 도구가 됩니다.