# Debug Backend

> Systematic 5-step backend debugging flow for AI-coded FastAPI apps. Load this skill when a bug is reported, a test fails, or unexpected behavior appears in any backend layer. Forces layer isolation before touching code — prevents the "touch 8 files and make it worse" pattern.

- **Type:** Skill
- **Install:** `agentstack add skill-yerdaulet-damir-vibe-coding-rules-debug-backend`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yerdaulet-damir](https://agentstack.voostack.com/s/yerdaulet-damir)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yerdaulet-damir](https://github.com/yerdaulet-damir)
- **Source:** https://github.com/yerdaulet-damir/vibe-coding-rules/tree/main/.claude/skills/debug-backend
- **Website:** https://vibecodex-omega.vercel.app

## Install

```sh
agentstack add skill-yerdaulet-damir-vibe-coding-rules-debug-backend
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# debug-backend

Stop. Do not edit any file yet. Work through these 5 steps in order.

---

## Step 1 — Locate the layer

Run these greps to find where the bug lives. Check one layer at a time.

```bash
# Is it a routing problem? (wrong status code, missing auth, bad request parsing)
grep -n "HTTPException\|status_code\|Depends(" app/routers/.py

# Is it a service logic problem? (wrong calculation, wrong state transition)
grep -n "def \|raise \|return " app/services/.py

# Is it a repository problem? (wrong query, missing user_id scope, transaction issue)
grep -n "SELECT\|filter\|where\|FOR UPDATE" app/repositories/.py

# Is it a provider problem? (timeout, wrong response shape, missing error handling)
grep -n "httpx\|raise\|return\|except" app/providers/.py
```

**Decision: fix only in the layer where the bug lives. Never fix a service bug in the router.**

---

## Step 2 — Check the 3 most common AI antipatterns

These cause 80% of production bugs in AI-coded backends. Grep for each:

```bash
# Antipattern 1: SQLAlchemy Session leaked into services
grep -rn "AsyncSession\|Session\|from sqlalchemy" app/services/

# Antipattern 2: Provider returning raw dict instead of domain type
grep -rn "return {" app/providers/

# Antipattern 3: Business logic in router (calculation, state change, external call)
grep -c "await.*service\|await.*repo\|if.*balance\|FOR UPDATE" app/routers/*.py
```

| Result | Root cause | Principle |
|--------|-----------|-----------|
| Session in services | Hexagonal boundary broken | B1 |
| `return {}` from provider | Missing ACL | B3 |
| Logic in router | Layer violation | A3 / code-standards |
| No `user_id` filter in query | Multi-tenancy gap | security-rules |

---

## Step 3 — Write a reproducing test first

Before changing any production code, write a failing test that captures the exact bug.

```python
# Template: place in tests/unit/ or tests/integration/
async def test_():
    # Arrange: minimal setup that triggers the bug
    repo = FakeCreditsRepo()
    repo.seed_balance("user-1", Decimal("5.00"))
    service = CreditsUserService(repo=repo)

    # Act: call the exact code path that fails
    with pytest.raises(ValueError, match="Insufficient balance"):
        await service.charge("user-1", Decimal("10.00"), idempotency_key="idem-1")

    # Assert: prove the invariant that was violated
    assert await repo.get_balance("user-1") == Decimal("5.00")  # not negative
```

**Run it:** `pytest tests/unit/test_.py::test_ -v`
It must be RED before you fix anything.

---

## Step 4 — Fix in the correct layer

Minimum change. No opportunistic refactoring. No unrelated cleanup.

```
Router bug   → fix only app/routers/
Service bug  → fix only app/services/
Repo bug     → fix only app/repositories/
Provider bug → fix only app/providers/
```

After fixing: run the reproducing test. It must turn GREEN.

```bash
pytest tests/unit/test_.py::test_ -v
# Expected: PASSED
```

---

## Step 5 — Run architecture lint

```bash
bash scripts/lint-architecture.sh
```

Must exit 0. If a check fails, the fix introduced a new architecture violation — revert and fix properly.

---

## Common error → root cause table

| Error | Where to look first | Likely cause |
|-------|-------------------|--------------|
| `422 Unprocessable Entity` | Router — Pydantic schema | Wrong field type or missing required field |
| `500 Internal Server Error` | Service — exception not caught | Provider returned unexpected shape (dict not JobResult) |
| `KeyError: 'url'` | Provider — ACL missing | Provider response changed, parser not updated |
| `InsufficientFunds` on correct balance | Repo — concurrent hold | Two requests raced, no `FOR UPDATE` lock |
| `401` on authenticated route | Router — `Depends(get_current_user_id)` missing | Auth dependency not wired |
| Test passes, prod fails | Repo — fake vs real diverged | FakeCreditsRepo doesn't match CreditsRepoProtocol |
| Logs silent on error | Service — bare `except:` | Exception swallowed, add `logger.exception(...)` |

---

## Verification

The skill was applied correctly when:
- [ ] A failing test exists that reproduces the bug
- [ ] Fix touches exactly one layer
- [ ] `bash scripts/lint-architecture.sh` exits 0
- [ ] No unrelated files were modified
- [ ] The reproducing test is now green

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yerdaulet-damir](https://github.com/yerdaulet-damir)
- **Source:** [yerdaulet-damir/vibe-coding-rules](https://github.com/yerdaulet-damir/vibe-coding-rules)
- **License:** MIT
- **Homepage:** https://vibecodex-omega.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yerdaulet-damir-vibe-coding-rules-debug-backend
- Seller: https://agentstack.voostack.com/s/yerdaulet-damir
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.