Tutorial · v0.8.1

First workflow against Claude Code

This tutorial walks you through the full platform workflow against the real Claude Code adapter — from API key to a passing quality gate. Plan around 45 minutes. If you haven't installed the platform yet, do the quickstart first and come back.

Prerequisites

Step 1: Configure the Anthropic API key

Two ways to get the key into the platform:

Variant A: through the UI (recommended)

  1. Click your user icon in the top right.
  2. Choose "Integrations" from the popover (or navigate to /integrations).
  3. Click "Add Anthropic API key".
  4. Paste the key (starts with sk-ant-...) and save.

The key is AES-GCM-encrypted under the master key from your .env and stored in the database. Nobody sees it in plaintext after saving.

Variant B: via env variable

If you'd rather set it as an env var (e.g. for air-gap setups), add to your .env:

SOFTWAREFABRIK_ANTHROPIC_API_KEY=sk-ant-...

Then: docker compose down && docker compose up -d. The UI route is cleaner because it produces an audit log entry.

Step 2: Set the default adapter to claudecode

To avoid picking the adapter on every run, set the global default:

  1. Click "Settings" in the top right (or navigate to /einstellungen).
  2. Choose the "Adapter" tab.
  3. Set "Default execution adapter" to claudecode.
  4. Set "Default model for Claude Code" to claude-sonnet-4-6 (good price/performance for most tasks). For deeper architecture work, claude-opus-4-7 is stronger but more expensive.
  5. Save.

Changes propagate within at most 5 minutes (TTL cache). To see them immediately, click "Invalidate cache now" at the bottom of the settings page.

Audit trail: Every settings change creates an entry in audit_event. Right under the value in the settings UI you can see who last changed it (user subject + timestamp).

Step 3: New project with the wizard

Click "New project with assistant" or navigate to /wizard:

  1. Step 1 — template: choose "Modern Spring Boot Backend".
  2. Step 2 — questions: use realistic values:
    • Project title: Phonebook API
    • Vision: "REST API for a simple phonebook with CRUD endpoints and Postgres persistence."
    • Java version: 21
    • Database: Postgres
    • Architecture: hexagonal
    • Language: English
  3. Step 3 — quality gates: turn on ArchUnit and OWASP Dependency-Check. Leave Trivy and Playwright off (Trivy is for container builds, Playwright for frontends).
  4. Step 4 — summary: review all values and click "Create project".

You land in the project editor with all fields sensibly pre-filled. Among other things the wizard turned your answers into:

Drafts survive restart: If your browser crashes or you restart the platform, your wizard progress is saved in wizard_draft. The next visit to /wizard offers "Resume draft".

Step 4: Review and adjust the artifacts

In the project editor click "Generate Markdown artifacts". The platform produces six files. Read them once:

  1. PROJECT.md — the charter. Is the vision clear? Is the audience right?
  2. INSTRUCTIONS.md — the concrete brief for the agent. This is the most important file. Typos or ambiguities here are taken at face value by the agent.
  3. AGENTS.md — the role description of the team. Adjust preferredModel per role if needed.
  4. WORKFLOW.md — phase model and approval gates.
  5. DEFINITION_OF_DONE.md — when is the run done?
  6. README.md — entry point for the agent inside the workspace.

Fix anything that's unclear. Example: if INSTRUCTIONS.md says "create CRUD endpoints", spell out which fields a Person has (name, phone, email). The more precise, the smaller the chance of hallucinations.

Tip: Imagine handing the brief to an external developer you brief only via documents. Don't leave any implicit assumptions.

Step 5: First run – create the skeleton

Keep the first run small. Click "New run" or navigate to /runs/new:

  1. Project: pick Phonebook API.
  2. Run title: Create skeleton
  3. Goal: use a concrete prompt like this: 
    Set up the initial Maven project with Spring Boot 3.x.
Create:
- pom.xml with spring-boot-starter-web, spring-boot-starter-data-jpa, postgresql, h2 (test)
- Application class with @SpringBootApplication
- application.yml with Postgres config (local) and H2 (test profile)
- a simple Person entity with id, name, phone
- a PersonRepository as a Spring Data JPA repository
- a REST controller with GET /persons (return all)
- smoke test with @SpringBootTest that loads the context
- README explaining "how to start" and "how to test"
  4. Adapter: claudecode (default settings).
  5. Model: claude-sonnet-4-6.
  6. Click "Create run".

The run is in status DRAFT. Click "Move to READY", then "Start run".

Step 6: Click through phase approvals

While the run executes, it goes through five main phases. At critical transitions the platform waits for your explicit approval:

PhaseWhat happensApproval?
PROMPT_ASSEMBLYPlatform reads PROJECT.md + INSTRUCTIONS.md and builds the initial prompt.No, automatic.
WORKSPACE_PREPARATIONWorkspace directory created, git init, artifacts copied in, initial commit.No, automatic.
EXECUTIONPlatform launches claude --print <prompt> in the workspace. Agent writes files, makes commits.Yes (default policy). You click "Approve" before the agent starts.
VALIDATIONPlatform launches mvn verify in the workspace. Build and tests run.No, automatic.
COMPLETIONOn green build: status COMPLETED. On red build: NEEDS_CORRECTION.Yes. You confirm whether the result is acceptable.

Approval buttons appear next to the current phase. You can Approve or Reject — rejection moves the run to CANCELED.

Step 7: Read logs, inspect Git diff

During the EXECUTION phase Claude Code outputs stream live into the log area. Look for:

On the right side the Git view shows branches, commits and a diff viewer. Click any commit to see its diff. That's the most honest view of what the agent actually did — no marketing language, just code.

SSE live streaming: The logs use Server-Sent Events. If the connection drops briefly (e.g. Wi-Fi handover), the browser auto-reconnects after 5 seconds and replays the last 50 lines — no gap.

Step 8: Quality gate

After COMPLETION click the "Quality gate" tab. You launch the five reviewers:

Per reviewer you see findings with severity (LOW / MEDIUM / HIGH / CRITICAL) and a confidence score. The aggregated verdict is one of:

PASSED WARNING FAILED SKIPPED ERROR

Special rules: SECURITY/HIGH and ARCHITECTURE/CRITICAL are always blocking, regardless of policy. Reviewer crashes appear as ERROR — they are reported, not silently swallowed.

Typical findings on a first run:

Step 9: Build follow-up runs

One mega-run that does everything in one go rarely works in practice. Much better: small, focused follow-up runs. On the run list there's a button at the top: "New run from last setup". Three clicks, then:

  1. Run #2: goal "Write unit tests for PersonRepository and PersonController, cover all CRUD operations. Target: ≥ 80 % line coverage."
  2. Run #3: goal "Fix the 'Hardcoded password' quality-gate finding and replace the value with an env var reference in application.yml."
  3. Run #4: goal "Extend README.md with a 'Deployment' section including a docker-compose example, and an 'API examples' section with curl calls per endpoint."

Each of these runs uses the same workspace and writes into the same Git branch. After each run finishes, you can re-run the quality gate to see if findings shrink.

Step 10: Inspect the workspace

The workspace lives at ./workspaces/<run-id>/ (or the path configured in settings). Switch into it and look at what the agent built:

cd ./workspaces/<run-id>
ls -la
git log --oneline -20
git diff HEAD~5 HEAD

You can keep working from here — make your own commits, push to a remote, branch, merge. The platform leaves the workspace alone unless you start another run.

If you like the result, export the workspace:

# push into a fresh GitHub repo:
cd ./workspaces/<run-id>
git remote add origin git@github.com:your-user/phonebook-api.git
git push -u origin main

Tips for good prompts and run goals

When things go wrong – debug strategies

SymptomCauseFix
claude: command not foundPlatform can't find the CLI on PATH.In settings → Adapter, set the absolute path: /usr/local/bin/claude (Linux/macOS) or C:\Users\<user>\AppData\Local\claude\claude.exe (Windows). Or set env var SOFTWAREFABRIK_CLAUDECODE_COMMAND.
Run hangs in EXECUTIONClaude is waiting for interactive input (e.g. login required).Check the logs. Usually the fix is to run claude manually once and log in.
mvn verify fails immediatelyAgent didn't produce a Maven project or a broken pom.xml.Inspect the workspace by hand, understand the error, fire a follow-up run with a corrective goal.
Quality gate says ERRORA reviewer crashed (e.g. because the Aider CLI is missing).The quality-gate detail shows the failure per reviewer. Disable reviewers whose CLIs aren't installed in the settings.
Token budget exhaustedPlatform blocks new runs at 100 % of the daily budget.Settings → Budget. Raise the cap or wait until midnight (reset).
Run cancelled with WORKSPACE_LOCKEDPrevious run didn't release the lock (platform crash).Delete the workspace directory, create the run again. Known edge case.

Next steps

IntroductionGlossary and mental model of the platform.
Architecture overviewHow the platform ticks technically.
Quick startIf you want to onboard someone else.
FAQAnswers to typical questions.
LicensingTiers and limits in detail.
WhitepaperBackground on 76 pages.
Agentic Software Factory · Tutorial · v0.8.1 · from project draft to a passing quality gate