Module build prompt — standard template¶
This page contains the two prompts the human orchestrator gives to Claude Code for every module build. Copy and paste them verbatim, filling in the module ID and title.
Prompt 1 — start of module (give this first)¶
Replace MOD-NNN and [title] with the actual module.
I am assigning you MOD-NNN — [title].
Before writing any code, complete the following steps in order and do not
skip any of them.
STEP 1 — Fetch all wiki context simultaneously (all six — do not skip any):
https://bank-wiki.pages.dev/ai-context/systems/
https://bank-wiki.pages.dev/ai-context/architecture/
https://bank-wiki.pages.dev/ai-context/policies/
https://bank-wiki.pages.dev/ai-context/design/
https://bank-wiki.pages.dev/ai-context/delivery/
https://bank-wiki.pages.dev/ai-context/index/
STEP 2 — Read these source files from ../bank-wiki/:
source/entities/modules/MOD-NNN.yaml ← binding spec
source/entities/modules/MOD-NNN.md ← implementation detail
source/pages/goals/fr-register.md ← FR text for every ID in requirements:
source/pages/delivery/methodology.md ← quality gates and IaC rules
source/pages/delivery/acceptance-criteria.md
source/pages/design/system/data-models/SD0x-*.md ← data model for THIS repo's system domain
For EVERY module ID listed under dependencies: in MOD-NNN.yaml, read:
source/pages/design/modules/MOD-NNN.md ← if this file exists
Do this for ALL dependencies before reading anything else. These design docs
are the primary source of truth for SSM output paths, exact table/schema names,
Snowflake object names, event schemas, and integration contracts that your module
must consume. Do not infer, guess, or invent any value that is documented there.
source/pages/design/system/observability-standard.md ← if this module has Lambda handlers
source/pages/design/system/error-handling-standard.md ← if this module has Lambda handlers
source/pages/delivery/seed-consumers-guide.md ← if this module writes to Postgres
STEP 3 — State back to me, in full, before writing a single line of code:
a) What this module does — one paragraph in your own words
b) Every FR in the requirements list — ID and the full requirement text
c) Every row in policies_satisfied — policy code, mode, and exactly what
the automated test must verify (be specific: what input, what output,
what constitutes the negative case for GATE and LOG modes)
d) Every table (Postgres or Snowflake) this module reads or writes — exact
schema.table names from the data model page; column-level detail for
tables it writes
e) Every SSM parameter path this module reads from upstream modules, with
the name of the dependency design doc where you found each path — and
every SSM path it will write as an output for downstream modules
f) Every EventBridge event this module publishes or consumes — event name
and schema from the event catalogue
g) Module type: AWS IaC / Snowflake DDL / hybrid / application Lambda
h) The complete list of files you will create
i) What seed data this module needs (Postgres: Flyway + seed-consumers-guide;
Snowflake: DDL manifest entries)
j) For each dependency module: which design doc you read (or "no design doc
exists" if the file was absent), its key outputs that this module consumes
(SSM paths, table names, object names, event schemas), and any constraint
it imposes on this module's implementation
Do not proceed until I have confirmed your step 3 response is complete and
accurate. I will say "confirmed — proceed" when ready.
Prompt 2 — after confirmation (give this after confirming step 3)¶
Confirmed — proceed.
Reminder of non-negotiable quality gates before this module is done:
For IaC modules:
- One infrastructure integration test per FR (AWS SDK assertions against
deployed dev — not mocks)
- Policy satisfaction tests: one per policies_satisfied row
- GATE modes: negative test required
- LOG modes: immutability test required (attempt UPDATE/DELETE → must fail)
- SSM outputs table in docs/design/MOD-NNN.md listing every path written,
its value description, and which downstream modules consume it
For Lambda modules (add to the above):
- Unit tests: ≥ 80% line coverage
- One test per FR
- Structured log format test (observability compliance)
- Idempotency test if this module writes to ledger or processes payments
For all modules:
- docs/design/MOD-NNN.md — module technical design doc
- docs/handoffs/MOD-NNN-complete.handoff.md — wiki handoff file
The wiki spec is binding. If you discover a gap between what is built and
what the spec requires, build what the spec requires — do not adapt the
spec to what is convenient to build. Surface any genuine ambiguity before
proceeding.
**Smoke test (required for all modules):**
Every module must include `tests/verify-deployment.mjs`. This file is the
smoke test invoked by the CI pipeline as the final step to advance status
from Built to Deployed. Requirements:
- Must make at least one real AWS SDK call or HTTP request against a
deployed resource (not a local mock or stub).
- Must exit 0 on success and non-zero on any failure.
- Must NOT immediately call `process.exit(0)` without performing any
checks — the smoke test must verify at least one live resource.
- Is invoked as `node tests/verify-deployment.mjs` from the module root.
**SD06 (bank-risk-platform) quality gates:**
Modules in SD06 have additional quality gates beyond the standard set:
- Pulumi deploy must complete cleanly before any Snowflake steps.
- dbt build (`dbt build --select tag:mod-NNN`) must pass with all dbt
tests green.
- DCM Projects deploy (if `has_dcm=true`): DCM plan (`snow dcm plan`)
must run before Pulumi deploy; DCM deploy (`snow dcm deploy`) runs
after dbt build. DCM deploy is gated to non-prod environments until
DCM Projects reaches GA (ADR-054 §6).
- Integration tests run post-deploy — after Pulumi, dbt, and DCM have
all completed successfully.
- The smoke test (`tests/verify-deployment.mjs`) must check Snowflake
liveness as applicable: Dynamic Tables must have
`SCHEDULING_STATE='RUNNING'` and last refresh within the declared
`TARGET_LAG` window; Snowflake Tasks must have `STATE='STARTED'`.
MOD-104 catch-up prompt (one-time — use now)¶
MOD-104 was deployed without completing the required deliverables. Use this prompt to complete it retroactively.
MOD-104 (AWS shared infrastructure bootstrap) was deployed to dev but the
delivery methodology deliverables were not completed. Your task is to
produce everything that is missing.
STEP 1 — Fetch all wiki context simultaneously:
https://bank-wiki.pages.dev/ai-context/systems/
https://bank-wiki.pages.dev/ai-context/architecture/
https://bank-wiki.pages.dev/ai-context/policies/
STEP 2 — Read these source files from ../bank-wiki/:
source/entities/modules/MOD-104.yaml
source/entities/modules/MOD-104.md
source/pages/goals/fr-register.md ← FR-417, FR-418, FR-419, FR-420
source/pages/delivery/methodology.md ← IaC module section is new — read it
source/pages/delivery/acceptance-criteria.md
source/pages/design/system/data-models/SD07-data-platform.md
STEP 3 — Audit what exists. Check whether each of these is present in
the repo and complete:
- bootstrap/docs/design/MOD-104.md (or docs/design/MOD-104.md)
- SSM outputs table inside that design doc
- Infrastructure integration tests for FR-417, FR-418, FR-419, FR-420
- Policy satisfaction tests:
GOV-005 GATE — tag enforcement: negative test required
GOV-006 LOG — CloudTrail enabled; immutability test required
DT-002 GATE — encryption enforcement: negative test required
STEP 4 — Report the gaps. For each missing item, state exactly what is
missing and what you will build to fill it. Wait for my confirmation
before writing anything.
The spec requires the following for each policy satisfaction:
GOV-005 GATE: All AWS resources tagged with tenant_id, module_id, and
environment at IaC synthesis time. Untagged resources blocked by SCP.
Test: attempt to deploy a resource without the required tags → must be
blocked by SCP or tagging compliance gate. Negative test is the primary
evidence for GATE mode.
GOV-006 LOG: CloudTrail enabled across all accounts from bootstrap.
Test: verify CloudTrail trail exists and is logging to the correct S3
path. Verify log records are immutable — attempt to delete or modify a
CloudTrail log object → must fail (S3 Object Lock or bucket policy).
DT-002 GATE: KMS CMKs provisioned per data classification (bank/pii,
bank/financial, bank/operational). Encryption at rest enforced by S3
bucket policy and Kinesis encryption settings.
Test 1: verify three KMS keys exist with correct aliases.
Test 2: attempt to PUT an object to a protected S3 bucket without
server-side encryption → must be rejected by bucket policy.
Negative test required.
The SSM outputs table must list every /bank/{env}/... path written by
MOD-104, what it contains, and which downstream modules consume it. This
is the primary hand-off artefact — Phase 1 modules cannot be started
until this table exists and is accurate.
Pre-push checklist¶
Before every git push, run the five gates in pre-push-checklist.md.
These catch lockfile drift, changes: rule scope gaps, immutability fixture collisions,
reserved-concurrency budget overruns, and column-name typos in test SQL — the five
categories that most commonly cause failed pipelines on first push.
Notes for the orchestrator¶
Always give Prompt 1 first and wait for the step 3 confirmation before giving Prompt 2. The confirmation step is the quality control point — if the agent's understanding of the spec is incomplete at step 3, the implementation will be incomplete. Fix it at step 3, not after the code is written.
If tests are failing, do not ask the agent to fix the tests. Ask it to re-read the spec and identify what is missing in the implementation. Tests fail because the implementation is wrong or incomplete, not because the tests are wrong.
If the agent proposes deviating from the spec (e.g. "I'll use X instead of Y because..."), stop it. The spec is the decision. If the spec is wrong, raise it here (in bank-wiki) so the decision is recorded. Do not accept undocumented deviations in code.