Hire by Technology
SERVICES
Contents
Share this article
Key Takeaways
Claude Code's default configuration works well for general software engineering, but may introduce risk for a fintech team building payment systems, KYC pipelines, and compliance infrastructure.
Left alone, Claude Code will suggest FLOAT for monetary amounts, or will write payment retry logic without a client-generated idempotency key, the exact gap that causes a customer to get double-charged when their connection drops mid-request.
It will model KYC verification as a plain verified: boolean, and log a full PAN in a payment service.
These issues directly affect users through things like double charges and create issues in regulatory audits.
The teams getting genuinely good output from Claude Code on financial code are the ones who built that configuration layer before Claude Code touched a single payment mutation.
This piece walks through how fintech teams use Claude Code in production, including CLAUDE.md, Stop hooks, subagents, and the specific fintech workflows where the combination earns its keep.
If you need skilled developers familiar with using AI assistants in fintech development to increase productivity without creating risks, we can assist.
CLAUDE.md creates context across every Claude Code session in a project.
For a fintech team, it's where the domain conventions that prevent the default financial code mistakes actually live.
A properly written fintech CLAUDE.md means instructions specific to fintech sit in the context window automatically instead of depending on someone remembering to type it into a prompt.
Here's what a production fintech CLAUDE.md typically covers:
# Monetary Precision - NON-NEGOTIABLE
- ALL monetary amounts: DECIMAL(19,4) or integer minor units (cents/pence)
- NEVER use FLOAT, DOUBLE, or JavaScript ‘number’ for monetary values
- Use the ‘Money’ value object from ‘src/domain/money.ts’ for arithmetic
- Reason: IEEE 754 floating-point can't represent many decimal fractions exactly, so the errors compound at transaction volume into real reconciliation discrepancies
# Payment Idempotency - ALL PAYMENT MUTATIONS
- Every payment mutation MUST include a client-generated idempotency key
- Use the ‘IdempotencyKey’ type from ‘src/domain/idempotency.ts’
- Pattern: client generates a UUID before calling the payment API; server checks the key before processing; the idempotency record writes atomically with the payment in a single DB transaction
- Reason: prevents double-charges when a client retries after a network failure
# KYC State Machine - NEVER USE BOOLEANS
- KYC verification status: ‘KycStatus’ enum in ‘src/domain/kyc.ts’
- Valid states: PENDING or UNDER_REVIEW or APPROVED/REJECTED/NEEDS_EDD
- EDD (Enhanced Due Diligence) triggers: transaction > $10K, PEP match, high-risk country flag
- NEVER: ‘verified: boolean’, ‘kycPassed: boolean’, or any boolean flag
- Reason: a boolean can't represent ongoing monitoring or EDD transitions
# PCI DSS Logging - DO NOT LOG IN SCOPED SERVICES
- Services under ‘/services/payment/*’ and ‘/services/card/*’ are PCI DSS scoped
- NEVER log: card numbers, CVV, full PAN, expiry dates, or any cardholder data
- Safe to log: transaction ID, masked PAN (last 4), amount (via the Money type), merchant ID, timestamp, user ID
- When in doubt, log less, not more
# SOX Payment Controls - DUAL APPROVAL REQUIRED
- Payment instructions over $50,000 require the dual-approval workflow
- Use ‘DualApprovalWorkflow’ from ‘src/workflows/approval.ts’
- Audit trail: every approval action logs the approver ID, timestamp, and full payment details
Claude Code's own best-practices guidance mentions that, if Claude Code already does something correctly without an instruction, you should delete the instruction or turn it into a hook instead.
A CLAUDE.md where half the rules describe default behavior anyway just adds noise.
Related Reading: Hire AI Developers
A Stop hook is a script Claude Code runs right when it thinks a turn is finished. If the script signals a block, Claude Code has to keep working.
This is a real gate, and for fintech teams, it's probably the most underused piece of Claude Code's configuration surface that we see.
Only exit code 2 blocks a Stop hook. Exit code 1, the conventional "this failed" signal in almost every other context, is treated as a non-blocking error on a Stop hook.
Claude Code logs a hook-error notice and lets the turn end anyway.
A compliance gate written with exit 1 actually enforces nothing.
It's also worth checking the stop_hook_active flag Claude Code passes in on each run and exiting cleanly if it's already true; a hook that keeps failing can loop.
Four Stop hook patterns fintech teams actually run:
#!/bin/bash
# Blocks any turn that introduces FLOAT/DOUBLE types in financial fields
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
for file in $(git diff --name-only HEAD); do
if grep -n "FLOAT\|DOUBLE\|: number" "$file" | grep -i "amount\|price\|balance\|fee\|rate"; then
echo "COMPLIANCE GATE FAILED: FLOAT type detected in a financial field" >&2
echo "Use DECIMAL(19,4) or integer minor units. See CLAUDE.md." >&2
exit 2
fi
done
exit 0
#!/bin/bash
# Blocks payment mutations missing idempotency key handling
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
for file in $(git diff --name-only HEAD | grep -E "payment|charge|transfer"); do
if grep -q "createPayment\|processCharge\|initiateTransfer" "$file"; then
if ! grep -q "IdempotencyKey\|idempotencyKey" "$file"; then
echo "COMPLIANCE GATE FAILED: payment mutation missing an idempotency key" >&2
echo "All payment mutations require IdempotencyKey. See CLAUDE.md." >&2
exit 2
fi
fi
done
exit 0
#!/bin/bash
# Blocks log statements that look like cardholder data in scoped services
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
for file in $(git diff --name-only HEAD | grep -E "services/(payment|card)/"); do
if grep -nE "log\.(info|warn|error|debug).*\b(card|pan|cvv|expir)" "$file" -i; then
echo "COMPLIANCE GATE FAILED: possible cardholder data in a log statement" >&2
echo "Review the PCI DSS logging rules in CLAUDE.md." >&2
exit 2
fi
done
exit 0
#!/bin/bash
# Blocks completion until a dependency scanner passes, only when deps changed
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
if git diff --name-only HEAD | grep -q "package.json"; then
snyk test --severity-threshold=high
if [ $? -ne 0 ]; then
echo "COMPLIANCE GATE FAILED: high-severity vulnerability found" >&2
echo "Resolve before completing this task." >&2
exit 2
fi
fi
exit 0
Claude Code caps consecutive Stop-hook blocks at eight by default (configurable through an environment variable) and ends the session with a warning rather than looping forever, which is exactly why the stop_hook_active check above matters.
Claude Code's subagent system lets a lead agent spawn a separate agent with a narrow context and a specific job.
We like this in fintech specifically because it creates a review pipeline that runs before a human ever looks at the code.
Once Claude Code finishes implementing a payment feature, the lead agent spawns a subagent scoped specifically to fintech review:
You are a senior fintech security engineer reviewing code for financial correctness and compliance. Check the changed files for:
Report each issue with file, line, description, and the correct pattern. Do not suggest fixes; report only. The human engineer implements fixes.
Something like this mirrors a pattern that's now fairly common in the wider Claude Code community, where a specialist reviewer subagent with a narrow domain brief runs automatically rather than only when someone remembers to ask for it.
Before any implementation code gets written, the lead agent spawns a subagent to write the tests first:
Write the test suite for the payment idempotency requirements before any implementation code. Cover a duplicate idempotency key on a completed payment (should return the existing result, no new charge), a duplicate key on an in-flight payment (should return 409 Conflict), an expired idempotency key (treated as a new payment), and concurrent duplicate submissions with the same key (exactly one should process). Use the project's test framework from CLAUDE.md. Do not implement the feature; tests only.
A second subagent, which runs separately, tries to refute the first one's findings before a human wades in:
You are a QA engineer reviewing the security engineer's findings. For each flagged issue, determine whether it's a genuine compliance violation or a false positive based on this project's CLAUDE.md conventions. Classify each as CONFIRMED, FALSE_POSITIVE, or NEEDS_HUMAN_REVIEW.
At real scale, this stops being a one-engineer setup.
Related Reading: AI Boosts Remote Developer Productivity: Managing Fintech Development
There are a couple of useful workflows our developers use consistently to produce value and increase productivity.
This is probably the highest-value pattern for a fintech team adopting Claude Code.
An engineer describes the payment feature in plain language, a test-writer subagent generates the idempotency tests, the decimal precision regression tests, and the happy-path and failure-mode tests.
The engineer then reviews and approves those tests, and Claude Code implements them. Finally, the Stop hooks run.
The security-engineer subagent reviews the result, and the engineer reviews the combined output.
Since the tests exist before the implementation, idempotency coverage is the starting point.
A single session, using Claude Code's large context window, that is used to audit an existing KYC implementation end-to-end:
"Audit all KYC-related code across this service. For each KYC status field or variable, determine: (a) whether it's a boolean or a state machine enum, (b) which valid state transitions are implemented, (c) which transitions are missing against the spec in CLAUDE.md, and (d) whether EDD triggers are correctly implemented. Produce a table: file, field name, implementation type, missing transitions, EDD gap."
This work would otherwise consume two or three days of a senior engineer's time, but by doing this, it runs in a single session. The output is an audit report, so human engineers still implement whatever it finds.
For when a PCI DSS or SOC 2 finding needs fixing across several services at once, you can use Claude Code to scan every affected service for the specific finding, and produce a remediation plan listing each affected file and the correct fix that the engineer reviews and approves.
Once that is done, Claude Code implements it with the relevant Stop hook active so it can't introduce a new instance of the same violation, and the security-engineer subagent verifies each remediated file afterward.
In this case, engineers could use the same large-context advantage for a refactor that's too big for one engineer to hold in their head.
"Audit every payment mutation across [list of services] for idempotency key handling. Produce: a list of mutations missing idempotency keys, the correct implementation for each using this project's IdempotencyKey type, and a migration plan that adds idempotency without breaking existing clients."
Related Reading: Claude Code vs Cursor for Fintech Engineering Teams
A single engineer's CLAUDE.md and hooks work fine for that engineer. But getting a whole fintech team to use Claude Code consistently needs shared configuration that doesn't depend on each person rebuilding it themselves.
For a fintech engineering team scaling Claude Code past ten or so engineers, consider the following to make the process easier:
Related Reading: GitHub Copilot vs Cursor for Fintech: What Changes in June 2026
CLAUDE.md, Stop hooks, and a security-engineer subagent together produce noticeably safer financial code than Claude Code's defaults. They don't produce safe financial code without a human reviewing it.
CLAUDE.md only prevents the mistakes someone thought to write down. The reviewer needs to know the domain well enough to notice what's absent, and who can make major architectural decisions that set you up to scale long-term.
Remember, tooling makes a competent engineer faster. It doesn't substitute for competence.
Trio places pre-vetted LATAM fintech engineers who configure Claude Code correctly and know how to review its output for the specific financial code errors that hooks and subagents don't catch.
Expertise
Subscribe to our newsletter
Related
Content
Continue Reading
