agentleFS
Sign inStart free
sergeeeysergeeey/Claude-cod-top-2026/skills/extensions/intended-vs-implemented/SKILL.md

intended-vs-implemented

Skill9 starsChanged 6 months agoMITView on GitHub

USE when you need to find gaps between what documentation claims the system does vs what the code actually does. Catches high-value bugs that linters miss: permissions documented but unenforced, endpoints marked internal that accept external calls, data classified as private that leaks. ALWAYS cite both documentation claim AND code evidence — no speculation. Triggers: /intended-vs-implemented, docs vs code, intent vs reality, задокументировано vs реализовано, docs не совпадают с кодом, что обещано vs что делает, audit intent, verify documented behavior. [STATUS: review] [CONFIDENCE: high] [REVIEWED: 2026-08-11]

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Create a free account to mount
Files
SKILL.md
<!-- BSV — Brief Skill View | поиск: BSV Скил : intended-vs-implemented TL;DR : Ищет разрыв между задокументированным поведением и реальным кодом Вызов : `/intended-vs-implemented`, 'docs vs code', 'задокументировано vs реализовано' НЕ для : Синтаксических ошибок (ruff/mypy), стиля кода, coverage -->

/intended-vs-implemented — Audit: Docs vs Code

Когда использовать

Когда нужно проверить что система реально делает то что задокументировано:

  • Security review: "permissions enforced" — а они правда enforced?
  • API audit: endpoint помечен internal-only — принимает ли внешние вызовы?
  • Data privacy: поле помечено private — утекает ли публично?
  • Pre-release gate: README claims feature X — реализована ли X полностью?

Это третий слой верификации после синтаксиса (ruff/mypy) и тестов (pytest):

ruff/mypy → корректность синтаксиса
pytest    → ожидаемое поведение кода
/intended-vs-implemented → соответствие документированному намерению

Протокол (5 шагов)

Шаг 1 — Собрать Intent (документация как claims)

Читать: README.md, docs/, CLAUDE.md, docstrings, inline comments с # WHY:.

Для каждого claim записать:

CLAIM: [что утверждается]
SOURCE: [файл:строка]
TYPE: [security | privacy | access-control | behavior | performance]

Шаг 2 — Найти Implementation Evidence

Для каждого claim — найти реальный код который его реализует (или не реализует):

# Пример: claim "PII never logged"
grep -rn "logger\|logging\|print\|structlog" hooks/ --include="*.py" | \
  grep -iE "email|phone|password|ssn|card"

# Пример: claim "only authenticated users reach /admin"
grep -rn "admin\|auth\|permission" hooks/ --include="*.py"

Каждый результат — [VERIFIED-grep] или [VERIFIED-read].

Шаг 3 — Сравнить Claim vs Evidence

ClaimDocumented inEvidence in codeMatch?
"PII auto-redacted"README:198scripts/redact.py PATTERNS (national ID/card/IBAN/email/phone) + clean()✅
"SQL uses parameterized queries"rules/security.md:12grep → 0 raw string SQL✅
"Secrets redacted before external MCP calls"scripts/redact.py:3-5 (module docstring)same PATTERNS list (API keys/tokens) + main() PreToolUse entrypoint✅
"X feature available"README:X???❌ GAP

Шаг 4 — Классифицировать Gaps

Оставлять только gaps которые пересекают реальную границу:

  • Trust boundary: непроверенный внешний ввод достигает логики
  • Data boundary: private данные утекают в logs/response
  • Cost boundary: неограниченный ресурс доступен без проверки
  • Tenant boundary: данные одного пользователя видны другому

Не считать finding'ом: косметическое расхождение docs vs code без реального риска.

Шаг 5 — Отчёт с Evidence Markers

Каждый finding обязательно содержит:

## FINDING: [название]
Severity: HIGH | MEDIUM | LOW
Type: [security | privacy | behavior]

CLAIMED (docs):
  > "[точная цитата]"
  Source: [файл:строка] [VERIFIED-read]

IMPLEMENTED (code):
  > "[что реально делает код]"
  Evidence: [файл:строка] [VERIFIED-grep]

GAP: [конкретное расхождение — одно предложение]
FIX: [минимальное исправление]

Запрещено: [HYPOTHESIS] без tool-verified evidence на HIGH/MEDIUM findings. Правило из rules/audit-verification-gate.md.

Интеграция с нашим стеком

  • Используй после ruff + pytest — они должны быть зелёными
  • Findings HIGH/MEDIUM → передать в sec-auditor агент для подтверждения
  • Findings → записать в .claude/memory/decisions.md как [AVOID] паттерн
  • Для security gaps → запустить /threat-modeling для оценки вектора атаки

Пример быстрого запуска

"Проверь что README-claim 'PII auto-redacted before external MCP calls'
 реально реализован в hooks/"

Claude: читает README claim → grep hooks/ → читает redact_pii.py → сравнивает → отчёт с [VERIFIED-grep] / [VERIFIED-read] маркерами.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free