ln-643-api-contract-auditor by levnikolaevich/claude-code-skills
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-643-api-contract-auditor路径说明: 文件路径(
shared/、references/、../ln-*)是相对于技能仓库根目录的。如果在当前工作目录中未找到,请定位此 SKILL.md 文件所在的目录,然后向上返回一级即为仓库根目录。如果缺少shared/目录,请通过 WebFetch 从https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}获取文件。
专门审计 API 契约、服务边界处的方法签名以及 DTO 使用模式的工作者。
超出范围(由 ln-623-code-principles-auditor 负责):
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
- pattern: "API Contracts" # 模式名称
- locations: string[] # 服务/API 目录
- adr_reference: string # 相关 ADR 的路径
- bestPractices: object # 来自 MCP Ref/Context7 的最佳实践
- output_dir: string # 例如:"docs/project/.audit/ln-640/{YYYY-MM-DD}"
# 领域感知(可选,来自协调器)
- domain_mode: "global" | "domain-aware" # 默认:"global"
- current_domain: string # 例如:"users", "billing"(仅在领域感知模式下)
- scan_path: string # 例如:"src/users/"(仅在领域感知模式下)
必须阅读: 加载 shared/references/two_layer_detection.md 以了解检测方法。加载 references/detection_patterns.md - 所有 5 条规则的语言特定 Grep 模式。
scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root
1. 查找 API 层:Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. 查找服务层:Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. 查找领域层:Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. 映射:哪些 API 端点调用了哪些服务
必须阅读: 使用 detection_patterns.md 中每条规则的语言特定 Grep 模式。
---|---|---|---
1 | 层泄漏 | 高/中 | 服务/领域层接受 HTTP 类型(Request、parsed_body、headers)
2 | 缺失 DTO | 中/低 | 4+ 个参数在 2+ 个方法中重复出现而未分组为 DTO
3 | 实体泄漏 | 高/中 | API 返回 ORM 实体而未使用响应 DTO。降级情况:无外部消费者的内部 API → 低
4 | 错误契约 | 中/低 | 同一服务中混合使用错误模式(raise + return None)
5 | 冗余重载 | 低/中 | 方法对使用 _with_/_and_ 后缀,仅相差 1-2 个参数
6 | 架构诚实性 | 高/中 | 读取命名函数(get_/find_/check_/validate_/is_/has_)的函数体包含写入副作用。排除项遵循 shared/references/ai_ready_architecture.md
范围边界: 跳过重复性发现(由 ln-623 负责),仅报告架构边界相关发现。
合规性评分 (0-100):
| 标准 | 分值 |
|---|---|
| 无层泄漏(服务中无 HTTP 类型) | +35 |
| 一致的错误处理模式 | +25 |
| 遵循项目命名约定 | +10 |
| 读取命名函数中无隐藏副作用 | +10 |
| 无实体泄漏到 API | +20 |
完整性评分 (0-100):
| 标准 | 分值 |
|---|---|
| 所有服务方法都有类型化参数 | +30 |
| 所有服务方法都有类型化返回值 | +30 |
| 为复杂数据定义了 DTO | +20 |
| 错误类型已记录/类型化 | +20 |
质量评分 (0-100):
| 标准 | 分值 |
|---|---|
| 服务方法中无非布尔标志参数 | +15 |
| 无隐藏写入操作的不透明返回类型 | +10 |
| 无超过 5 个参数且未使用 DTO 的方法 | +25 |
| 模块内命名一致 | +25 |
| 无冗余重载 | +25 |
实现评分 (0-100):
| 标准 | 分值 |
|---|---|
| DTO/模式存在且被使用 | +30 |
| 存在类型注解 | +25 |
| 边界处有验证(Pydantic、Zod) | +25 |
| API 响应 DTO 与领域层分离 | +20 |
必须阅读: 加载 shared/references/audit_worker_core_contract.md 和 shared/references/audit_scoring.md。
主要评分 使用惩罚公式(与所有工作者相同):
penalty = (critical × 2.0) + (high × 1.0) + (medium × 0.5) + (low × 0.2)
score = max(0, 10 - penalty)
诊断子评分(每项 0-100)单独计算,并仅在 AUDIT-META 中报告用于诊断目的。
必须阅读: 加载 shared/references/audit_worker_core_contract.md 和 shared/templates/audit_worker_report_template.md。
# 在内存中构建 Markdown 报告,包含:
# - AUDIT-META(扩展:评分[基于惩罚] + 诊断评分 compliance/completeness/quality/implementation)
# - 检查表(layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - 发现表(按严重性排序的问题)
# - DATA-EXTENDED:包含 principle + domain 字段的问题数组(用于跨领域聚合)
IF domain_mode == "domain-aware":
写入到 {output_dir}/643-api-contract-{current_domain}.md
ELSE:
写入到 {output_dir}/643-api-contract.md
报告已写入:docs/project/.audit/ln-640/{YYYY-MM-DD}/643-api-contract-users.md
评分:6.75/10 (C:65 K:70 Q:55 I:80) | 问题:4 (H:2 M:1 L:1)
必须阅读: 加载 shared/references/audit_worker_core_contract.md。
必须阅读: 加载 shared/references/audit_worker_core_contract.md。
{output_dir}/643-api-contract[-{domain}].md(原子性单次写入调用)references/detection_patterns.md../ln-640-pattern-evolution-auditor/references/scoring_rules.md../ln-640-pattern-evolution-auditor/references/pattern_library.md版本: 2.0.0 最后更新: 2026-02-08
每周安装量
148
仓库
GitHub 星标数
245
首次出现
2026年2月7日
安全审计
安装于
cursor137
gemini-cli136
github-copilot135
opencode135
codex134
claude-code134
Paths: File paths (
shared/,references/,../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. Ifshared/is missing, fetch files via WebFetch fromhttps://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.
Specialized worker auditing API contracts, method signatures at service boundaries, and DTO usage patterns.
Out of Scope (owned by ln-623-code-principles-auditor):
- pattern: "API Contracts" # Pattern name
- locations: string[] # Service/API directories
- adr_reference: string # Path to related ADR
- bestPractices: object # Best practices from MCP Ref/Context7
- output_dir: string # e.g., "docs/project/.audit/ln-640/{YYYY-MM-DD}"
# Domain-aware (optional, from coordinator)
- domain_mode: "global" | "domain-aware" # Default: "global"
- current_domain: string # e.g., "users", "billing" (only if domain-aware)
- scan_path: string # e.g., "src/users/" (only if domain-aware)
MANDATORY READ: Load shared/references/two_layer_detection.md for detection methodology. Load references/detection_patterns.md — language-specific Grep patterns for all 5 rules.
scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root
1. Find API layer: Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. Find service layer: Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. Find domain layer: Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. Map: which services are called by which API endpoints
MANDATORY READ: Use detection_patterns.md for language-specific Grep patterns per rule.
---|---|---|---
1 | Layer Leakage | HIGH/MEDIUM | Service/domain accepts HTTP types (Request, parsed_body, headers)
2 | Missing DTO | MEDIUM/LOW | 4+ params repeated in 2+ methods without grouping DTO
3 | Entity Leakage | HIGH/MEDIUM | ORM entity returned from API without response DTO. Downgrade when: internal API with no external consumers → LOW
4 | Error Contracts | MEDIUM/LOW | Mixed error patterns (raise + return None) in same service
5 | Redundant Overloads | LOW/MEDIUM | Method pairs with _with_/_and_ suffix differing by 1-2 params
6 | Architectural Honesty | HIGH/MEDIUM | Read-named function (get_/find_/check_/validate_/is_/has_) body contains write side-effects. Exclusions per shared/references/ai_ready_architecture.md
Scope boundary: SKIP DUPLICATION findings (owned by ln-623), REPORT only ARCHITECTURE BOUNDARY findings.
Compliance Score (0-100):
| Criterion | Points |
|---|---|
| No layer leakage (HTTP types in service) | +35 |
| Consistent error handling pattern | +25 |
| Follows project naming conventions | +10 |
| No hidden side-effects in read-named functions | +10 |
| No entity leakage to API | +20 |
Completeness Score (0-100):
| Criterion | Points |
|---|---|
| All service methods have typed params | +30 |
| All service methods have typed returns | +30 |
| DTOs defined for complex data | +20 |
| Error types documented/typed | +20 |
Quality Score (0-100):
| Criterion | Points |
|---|---|
| No boolean flag params in service methods | +15 |
| No opaque return types hiding write actions | +10 |
| No methods with >5 params without DTO | +25 |
| Consistent naming across module | +25 |
| No redundant overloads | +25 |
Implementation Score (0-100):
| Criterion | Points |
|---|---|
| DTOs/schemas exist and are used | +30 |
| Type annotations present | +25 |
| Validation at boundaries (Pydantic, Zod) | +25 |
| API response DTOs separate from domain | +20 |
MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/references/audit_scoring.md.
Primary score uses penalty formula (same as all workers):
penalty = (critical × 2.0) + (high × 1.0) + (medium × 0.5) + (low × 0.2)
score = max(0, 10 - penalty)
Diagnostic sub-scores (0-100 each) are calculated separately and reported in AUDIT-META for diagnostic purposes only.
MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/templates/audit_worker_report_template.md.
# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: issues array with principle + domain fields (for cross-domain aggregation)
IF domain_mode == "domain-aware":
Write to {output_dir}/643-api-contract-{current_domain}.md
ELSE:
Write to {output_dir}/643-api-contract.md
Report written: docs/project/.audit/ln-640/{YYYY-MM-DD}/643-api-contract-users.md
Score: 6.75/10 (C:65 K:70 Q:55 I:80) | Issues: 4 (H:2 M:1 L:1)
MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
{output_dir}/643-api-contract[-{domain}].md (atomic single Write call)references/detection_patterns.md../ln-640-pattern-evolution-auditor/references/scoring_rules.md../ln-640-pattern-evolution-auditor/references/pattern_library.mdVersion: 2.0.0 Last Updated: 2026-02-08
Weekly Installs
148
Repository
GitHub Stars
245
First Seen
Feb 7, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
cursor137
gemini-cli136
github-copilot135
opencode135
codex134
claude-code134
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
36,300 周安装