Qodo Quality-First AI Coding Workshop

This repo is the source of truth for a one-hour hands-on workshop on building a quality-first AI coding workflow with Qodo.

You will practice this loop:

plan -> read repo rules -> use repo skills -> write tests -> implement -> run local gates -> open PR -> Qodo review -> PR Resolver remediation

What You Are Building

This is a self-contained FastAPI payments API used to practice quality-first AI coding.

It has no separate frontend and no external service dependencies. You will interact with the app through FastAPI’s browser docs at /docs.

The goal is not to build a production payment system. The goal is to practice a repeatable workflow:

plan -> read repo rules -> write tests -> implement -> run local gates -> open PR -> review with Qodo -> resolve findings

What This Repo Is Teaching

This workshop is a small API wrapped in a quality system. Every directory is here to teach one part of quality-first AI coding:

• make the task explicit before code changes
• give the agent local standards it can read
• give the agent skills that describe how to work
• prove behavior with tests
• catch deterministic issues with static analysis and local gates
• use Qodo review as an independent review layer
• remediate findings and verify again

You can describe this as SDLC or ADLC quality control. The same standards show up before coding, during coding, and after coding:

Read the presenter-focused lesson in docs/07-workshop-teaching-guide.md.

Repository Structure

The app is intentionally small so the quality system is easy to inspect. The teaching point is the loop around the code, not the size of the feature.

Workshop App

Run the app locally:

make setup
make run

Open:

http://127.0.0.1:8000/docs

Also available:

http://127.0.0.1:8000/redoc
http://127.0.0.1:8000/openapi.json

This workshop app is API-first. The browser UI is FastAPI /docs, not a separate React dashboard.

Choose Your Lane

• Hands-on: fork, clone, configure Qodo, make the change, open a PR.
• Pair/observe: follow the README and inspect the gates while someone else codes.
• Async later: use this repo as a complete guided workshop after the session.

One-Hour Flow

Quality Gate Checkpoints

Use these checkpoints to know what you have completed at each step. Each gate should leave behind visible proof that the workflow is moving forward.

• Setup gate: make doctor, make setup, and starter make verify run successfully. You have a working local repo before asking an agent to change application behavior.
• Qodo access gate: your fork is connected to Qodo, your API key is stored outside git, and official plus repo-local skills are installed or documented as unavailable. You have a review layer ready without committing credentials.
• Standards gate: the relevant PAY-* rules are selected, linked rule docs are read, repo skills are identified, and optional Qodo rule status is recorded. You have turned the task into explicit quality constraints.
• Planning and TDD gate: the high-level plan, build-session execution plan, and smallest useful failing behavior tests are identified or written. You have made the expected behavior observable before production code changes.
• Local verification gate: targeted tests and make verify pass without disabling Ruff, Pyright, Bandit, Pytest, Semgrep, or commit checks. You have deterministic evidence that the change preserves the local contract.
• PR review and remediation gate: the PR is open, Qodo findings are inspected, fixes or deferrals are documented, and make verify is rerun after remediation. You have completed the review loop rather than stopping at a passing local run.

Prerequisites

Read docs/00-prerequisites.md.

Required:

• Git
• GitHub account
• GitHub CLI authenticated with gh auth login
• Python 3.11+
• uv
• Node.js and npm
• A coding agent such as Codex, Claude Code, Cursor, Windsurf, or Cline
• Qodo account

Setup

git clone 
cd qodo-quality-workshop-signalpay
make doctor
make setup
make verify

If setup fails, paste the make doctor output into your coding agent and ask it to fix your local environment.

Qodo Setup

1. Sign into the Qodo portal.
2. Connect GitHub to your fork.
3. Generate an API key from the Qodo portal.
4. Ask your coding agent to configure Qodo Skills.

For normal workshop use, store the key in a local-only Qodo config file:

{
  "API_KEY": "sk-..."
}

Save it at:

~/.qodo/config.json

Qodo Skills default to the production Qodo API. Set QODO_API_URL in this file only if your instructor gives you a non-production Qodo API endpoint.

Read:

• docs/01-qodo-portal-github.md
• docs/02-qodo-api-key-and-skills.md

Install official Qodo Skills:

npx skills add qodo-ai/qodo-skills/skills

Install repo-local workshop skills:

make install-skills

Repo-Local Rules

The default pre-coding context is committed in rules/README.md. Qodo portal rules are optional enrichment. Do not block the workshop on portal rule setup.

Repo-local rules are intentionally Markdown. That makes them readable by:

• attendees
• coding agents
• reviewers
• Qodo-hosted rule setup, when a team chooses to mirror or host the same standards in Qodo

In the workshop, local rules are the baseline. Qodo-hosted rules and skills can carry the same quality expectations into review, but they are enrichment rather than a prerequisite.

Repo-Local Skills

Repo-local skills are committed in skills/. They teach the agent how to work inside the rules.

For example, the payment-idempotency skill translates payment safety into concrete implementation checks: require Idempotency-Key, check auth before mutation, return the original response on retry, and avoid duplicate events.

Use skills/README.md to explain which skill belongs to each phase of the workflow.

Hands-On Task: Payment Workflow Safety

Your task is to add one small payment workflow: either a refund workflow or capture-retry handling. Choose one path for the workshop; do not try to build both.

This is intentionally a small change with production-shaped risk. Payment mutations are where AI-generated code can look correct while quietly breaking system guarantees. A retry can emit a duplicate event, a missing idempotency key can create duplicate work, an auth check can happen after state changes, or a response can drift from the public API contract.

The point of this exercise is to practice making an agent work inside a quality system before it writes code. You will force the agent to read local rules, select the PAY-* standards that apply, use the payment-idempotency skill, write behavior tests first, run deterministic gates, and then compare the result with Qodo review feedback.

By the end, you should be able to see the difference between “the agent changed files” and “the agent produced a change that preserved the system contract.” The expected output is a small PR with tests, verification evidence, and a review/remediation loop, not a large feature.

Preserve these guarantees:

• idempotency
• auth scope checks
• event contract shape
• one-event-per-idempotency-key behavior

Use this task as the input for the setup, planning, TDD, and verification prompts below.

Read docs/03-run-rules-before-coding.md, then start from:

• .plan/workshop-payment-task/plan.md
• .plan/workshop-payment-task/build-session-execution-plan.md

When presenting this step, point out that .plan/ is part of the lesson. The high-level plan explains intent and quality constraints. The build-session execution plan turns those constraints into an ordered agent workflow.

Definition of Done

The workshop task is complete when you have a small PR that includes:

• selected repo-local rules and optional Qodo rule status
• behavior tests and verification evidence
• a passing make verify run without weakened gates
• Qodo review evidence or the documented fallback path
• remediation notes for fixed or intentionally deferred findings

Copy/Paste Agent Prompts

Setup Prompt

Help me configure this repo for the Qodo workshop.

I have a Qodo API key from the Qodo portal.

Requirements:
- Do not commit the API key.
- Store it only in a safe local developer location or environment variable.
- Install or verify Qodo Skills.
- Read `AGENTS.md` and `rules/README.md`.
- Select the relevant repo-local rule IDs for the Hands-On Task and explain why each applies.
- Optionally compare those rules with qodo-get-rules if Qodo rules are available.
- If my local environment is missing dependencies, diagnose and fix them.

Planning Prompt

Use the repo-local workshop planning skill to turn the Hands-On Task in README.md into:
1. a high-level implementation plan
2. a build-session execution plan

Use `AGENTS.md`, `rules/README.md`, selected `PAY-*` rules, and the
payment-idempotency skill as constraints.
The plan must include an implementation skill handoff that names the first
implementation skill and the exact TDD prompt to run next.
Treat qodo-get-rules as optional enrichment if available.
Do not write code yet.

TDD Prompt

Run this only after the planning prompt has produced the high-level plan, build-session execution plan, and implementation skill handoff.

Use the workshop TDD/BDD skill.

Use the plan files just created.
Write the smallest failing tests first for the selected payment workflow path.
Cover one happy path and at least one failure path.
Do not implement production code until the failing tests prove the behavior gap.

Verification Prompt

Run the full local verification ladder.

If anything fails, classify the failure as formatting, linting, type checking, security/static analysis, behavior, or repo guideline compliance.
Fix the issue without weakening the gate.
Re-run verification.

Local Verification Gates

Run individual gates:

make lint
make typecheck
make security
make test
make semgrep

Run the full ladder:

make verify

Read docs/04-local-verification-gates.md.

These gates catch deterministic issues early:

• Ruff checks Python lint, imports, and maintainability.
• Pyright catches type and interface drift.
• Bandit checks common Python security risks.
• Pytest proves API behavior.
• Semgrep checks workshop-specific static-analysis patterns.
• CI reruns the same ladder on PRs.

Qodo review adds context-aware review after these gates; it does not replace them.

Open a PR and Let Qodo Review

git checkout -b feat/payment-workflow
git add .
git commit -m "feat(payments): add refund workflow"
git push -u origin feat/payment-workflow
gh pr create --fill

Read:

• docs/05-open-pr-and-qodo-review.md
• docs/06-pr-resolver-remediation.md

In the Qodo review, distinguish evidence from configuration. It is fine to say this repo contains local rules and skills. Only say Qodo used a skill in review when the review surface shows evidence such as Skill insights, a visible skills/context section, or a Qodo comment that names the skill.

Slides

The live companion deck is linked from slides/README.md.

Fallbacks

• Local setup failing? Paste make doctor output into your coding agent.
• Qodo API setup failing? Continue with repo skills, local gates, and the instructor demo.
• Qodo review delayed? Use the prepared instructor PR: Instructor demo: red refund workflow gate.
• Behind the room? Continue asynchronously from this README.