C# Web API 컨트롤러와 TypeScript/JavaScript 클라이언트를 교차 참조하여 계약 드리프트(contract drift) 및 중단적 변경 사항을 감지합니다.
- GitHub 스타
- 41,038
- 파일
- 1
- 마지막 커밋
- 2026년 11월 11일
- 라이선스
- MIT
- 허용된 도구
- —
api-breaking-change-detector skill은 무엇을 하나요?
C# Web API 컨트롤러와 TypeScript/JavaScript 클라이언트를 교차 참조하여 계약 드리프트(contract drift) 및 중단적 변경 사항을 감지합니다.
skill의 SKILL.md에서 생성된 요약입니다.
api-breaking-change-detector skill 정보
이 SKILL은 C# Web API 컨트롤러와 TypeScript 또는 JavaScript 클라이언트 간의 계약 드리프트를 감지할 수 있게 해줍니다. JSON 키 이름 변경이나 새로운 필수 파라미터 추가와 같은 백엔드 변경 사항이 React, Angular 또는 Vue와 같은 클라이언트 애플리케이션에 어떤 영향을 미치는지 개발자가 식별할 수 있도록 돕습니다. 또한 프론트엔드 코드에서 백엔드가 더 이상 처리하지 않는 필드를 전송하는 경우를 찾아내어, 런타임 버그가 운영 환경에 도달하기 전에 미리 방지할 수 있습니다.
사용자가 코드를 병합하기 전에 DTO 또는 컨트롤러 변경 사항을 클라이언트와 대조하여 감사해야 하는 경우 에이전트가 이 도구를 로드해야 합니다. OpenAPI 스펙 파일을 비교하는 도구와 달리, 이 SKILL은 실제 소스 코드를 직접 분석합니다. Program.cs를 분석하여 JSON 명명 정책을 확인하고, C# 11의 required 수정자를 검사하며, 정규화된 URL 매칭을 사용하여 Fetch 또는 Axios를 사용하는 수동 HTTP 호출을 찾아냅니다. 이 과정은 파일을 수정하는 대신 상세한 감사 보고서를 생성합니다.
agent가 수행할 수 있는 작업
- 1중단적 영향을 위한 DTO 변경 감사C# Data Transfer Object를 수정할 때 기존 프론트엔드 인터페이스가 깨지는지 확인합니다.
- 2API 계약 동기화 검증백엔드 컨트롤러와 TypeScript 클라이언트 모델이 동기화된 상태를 유지하는지 확인합니다.
- 3릴리스 전 엔드포인트 감사 수행운영 환경 릴리스 전에 잠재적인 중단적 변경 사항에 대해 전체 API 표면을 감사합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
api-breaking-change-detector skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.Claude Code에 api-breaking-change-detector skill 설치
~/.claude/skills/api-breaking-change-detector/SKILL.md
$ npx degit github/awesome-copilot/skills/api-breaking-change-detector ~/.claude/skills/api-breaking-change-detectorClaude Code (project)에 api-breaking-change-detector skill 설치
.claude/skills/api-breaking-change-detector/SKILL.md
$ npx degit github/awesome-copilot/skills/api-breaking-change-detector .claude/skills/api-breaking-change-detectorCodex에 api-breaking-change-detector skill 설치
~/.agents/skills/api-breaking-change-detector/SKILL.md
$ npx degit github/awesome-copilot/skills/api-breaking-change-detector ~/.agents/skills/api-breaking-change-detectorGemini CLI에 api-breaking-change-detector skill 설치
~/.gemini/skills/api-breaking-change-detector/SKILL.md
$ npx degit github/awesome-copilot/skills/api-breaking-change-detector ~/.gemini/skills/api-breaking-change-detectorClaude.ai에 api-breaking-change-detector skill 설치
npx degit github/awesome-copilot/skills/api-breaking-change-detector api-breaking-change-detector && zip -r api-breaking-change-detector.zip api-breaking-change-detector # claude.ai → Customize → Skills → + → Create skill → Upload a skill → api-breaking-change-detector.zip
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식
- 소스 저장소 연결 및 접근 가능github/awesome-copilot/skills/api-breaking-change-detector is public and reachablegithub.com/github/awesome-copilot/tree/HEAD/skills/api-break ↗통과
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-11github.com/github/awesome-copilot/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음No scripts in the skill folder통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/github/awesome-copilot/blob/HEAD/skills/api-break ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/github/awesome-copilot/blob/HEAD/skills/api-break ↗통과
- SKILL.md가 Agent Skills 형식을 따름Valid name and description; says when to use it; 73 linesgithub.com/github/awesome-copilot/blob/HEAD/skills/api-break ↗통과
SKILL.md
GitHub에서 보기API Breaking Change Detector
You are cross-referencing a C# Web API's actual contract (controllers, DTOs, route definitions) against its TypeScript/JavaScript consumers to find contract drift — in both directions — before it reaches production.
When to use this
Trigger when the user asks to:
- Check whether a DTO/controller change will break frontend or client applications
- Verify the client and backend API contract are still in sync
- Audit a specific endpoint, or the whole API surface, for breaking changes before a release
Do not use this for:
- Generating new API code from an OpenAPI spec (see
openapi-to-application-code) - Scaffolding new endpoints with OpenAPI docs (see
aspnet-minimal-api-openapi) - Comparing two OpenAPI spec files directly — this skill reads source code, not exported specs
Process
-
Discover Global JSON & Naming Policies:
- Check
Program.csorStartup.csfor active JSON options (e.g.JsonNamingPolicy.CamelCase,PropertyNamingPolicy, or NewtonsoftCamelCasePropertyNamesContractResolver). - Default to
camelCasefor TypeScript/JavaScript field mapping if global camelCase is configured, unless overridden by an explicit[JsonPropertyName("...")]attribute on the C# property. - Ignore C# properties annotated with
[JsonIgnore].
- Check
-
Identify the C# contract surface. For each Controller action in scope:
- Route: Base
[Route("...")]+ action[HttpGet("...")]/[HttpPost("...")]. Normalize route parameters (e.g.{id:int}or{id:guid}$\rightarrow${id}). - Request DTO: Extract property names, types, and requirement rules:
- Required if: annotated with
[Required],[BindRequired], has the C# 11requiredmodifier (public required string X), or is a non-nullable value type (int,Guid,bool) without a default value. - Optional if: nullable (
string?,int?), or has a default initializer.
- Required if: annotated with
- Response DTO: Property names, types, and nullability.
- Explicit Status Codes:
[ProducesResponseType(statusCode)]attributes and explicitStatusCode(...)return paths.
- Route: Base
-
Find the matching TypeScript/JavaScript consumer (with Normalized URL Matching):
- Auto-generated client match (high confidence): look for generated client files (NSwag/OpenAPI Generator output) and match by generated method/interface name directly.
- Hand-written service/client match (medium confidence):
- Search TypeScript/JavaScript files for HTTP client calls (
fetch,axios, AngularHttpClient,ky, etc.) whose normalized URL pattern matches the controller's route. - Normalize template strings and concatenations (e.g.,
${this.apiUrl}/users/${id}orbaseUrl + '/users/' + userId$\rightarrow$/users/{id}). - Match normalized routes against C# routes regardless of variable naming in TypeScript/JS.
- Search TypeScript/JavaScript files for HTTP client calls (
- No match found: report as "no client consumer located" rather than guessing — do not assume an endpoint is unused just because a match wasn't found statically.
- Label every finding with which of these three methods was used to locate it.
-
Compare backend → frontend/client (breaks the client):
- A DTO property renamed or removed that the TypeScript/JS interface or object model still expects
- A new required request field the client never sends
- A response status code the client doesn't handle (e.g. controller now returns 409 Conflict, but client error handler only handles 400/500)
- A response field's type changed (e.g.
long$\rightarrow$string, or non-nullable $\rightarrow$ nullable) in a way the client type assumes differently
-
Compare frontend/client → backend (stale/dead client code vs. silent bugs):
- Harmless dead field: Client sends a payload property the backend ignores without error.
- Silently broken bug (High Severity): Client logic reads a response property that the backend no longer returns (resulting in
undefinedat runtime and potential application failures).
-
Produce the report (see Output Format). This skill does not modify code.
Output Format
- Scope Audited — Controllers, DTOs, and TypeScript/JavaScript files audited, along with detected JSON naming policies (e.g.
camelCaseenabled viaProgram.cs). - Backend → Client Breaks — Grouped by endpoint: what changed, match method used (Auto-generated / Normalized Route Match), exact impact on the client, and severity (Compilation Error vs. Silent Runtime Failure).
- Client → Backend Drift — Stale fields sent or expected, explicitly distinguishing harmless dead fields from silently broken client UI logic.
- No Consumer Found — Unmatched backend DTOs/endpoints requiring manual confirmation.
- Match Confidence Summary — Breakdown of findings derived from auto-generated clients vs. normalized hand-written routes vs. unmatched routes.
Guidelines
- URL Normalization: Always strip query parameters (
?status=active) and normalize path parameters (${id}/:id/{id}) before comparing routes. - Naming Policies: Never assume a C# property name matches a TypeScript/JS property verbatim without checking for
[JsonPropertyName("...")]or globalJsonNamingPolicy.CamelCasesettings. - Modern C# Nuances: Check for C# 11
requiredkeyword and#nullable enableannotations (string?vsstring) when assessing required properties. - Framework Agnostic: Apply contract matching across any TypeScript or JavaScript client (Fetch, Axios, Angular, React, Vue, Svelte, Node.js).
- Never Fabricate: If no matching client service or DTO is found, report "No consumer located via static search" — never guess a pairing based purely on loose class names.
- Reporting Only: Do not modify code; output a scannable, actionable audit report.
이 스킬의 파일
1api-breaking-change-detector skill 질문
Claude Code에 api-breaking-change-detector skill을 어떻게 설치하나요?
npx degit github/awesome-copilot/skills/api-breaking-change-detector ~/.claude/skills/api-breaking-change-detector를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
api-breaking-change-detector skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
OpenAPI 스펙 파일을 사용하여 비교하나요?
아니요, 이 SKILL은 내보낸 OpenAPI 스펙 파일 대신 소스 코드를 직접 분석하여 작동합니다.
어떤 종류의 프론트엔드 클라이언트를 감사할 수 있나요?
React, Angular, Vue, Svelte, Node.js를 포함하여 Fetch, Axios 또는 NSwag을 사용하는 다양한 TypeScript/JavaScript 클라이언트를 지원합니다.
C# 명명 규칙을 어떻게 처리하나요?
Program.cs 또는 Startup.cs를 확인하여 camelCase와 같은 JSON 명명 정책을 체크하며, 명시적인 [JsonPropertyName] 속성을 준수합니다.
이 도구가 소스 코드를 수정하나요?
아니요, 이 도구는 감사 보고서만 생성하도록 설계되었으며 코드를 수정하지 않습니다.