A Claude Code skill that prompts solo builders to consider the invisible production layer of any build, alongside the visible MVP layer.
A configurable Claude Code skill written in Markdown. When it triggers on a build request, it walks the conversation through a structured set of phases that include classification questions, mandatory documentation templates, suggested security tooling, and reference checklists for common production concerns (security, GDPR/DSGVO, scaling, backups, bus factor, sunset).
What it actually does:
- Asks four classification questions before any code is written
- Assigns a risk tier (1–3) based on the answers and explains why
- Generates mandatory documentation files (
ICEBERG-REPORT.md,ASSUMPTIONS.md,BUS-FACTOR-PLAN.md,SUNSET-PLAN.md, etc.) - Suggests automated security tools to run (
npm audit,pip-audit,trufflehog,semgrep, Mozilla Observatory, SSL Labs) - Walks through a critical user path with 12 stress questions
- Produces a cross-AI review briefing for a second model
- Recommends a cool-down period before launch
What it does NOT do:
- It does not modify or execute your code automatically
- It does not block deployments or enforce anything at runtime
- It does not connect to any external service, send telemetry, or track usage
- It does not give legal, tax, or compliance advice
- It does not provide any warranty or certification
The skill is a structured prompt scaffold. Whether the AI you run it with actually follows the structure depends on that AI.
Solo builders without a development team, QA, or code-review colleagues — people building with Claude Code, Cursor, Aider, Lovable, Bolt, v0, or similar tools, who carry full responsibility for the result themselves.
It may also be useful for small teams looking for a lightweight pre-build checklist, but it was designed with the single-developer case in mind.
VISIBLE (what the AI tends to build)
┌─────────────────────────────────┐
│ UI · happy path · demo logic │
├─────────────────────────────────┤
│ │
│ Auth · backups · GDPR │
│ Rate limiting · logging │
│ Scaling · monitoring │
│ Encryption · caching │
│ Incident plan · sunset · ... │
│ │
└─────────────────────────────────┘
INVISIBLE (production reality)
The skill is built around the metaphor that the lower half tends to be skipped in AI-assisted builds, and that surfacing it as explicit prompts and documentation helps a solo builder decide what to address now versus later.
| Phase | Purpose |
|---|---|
| 1. Classify | Four questions about scale, criticality, data sensitivity, lifetime → tier assignment |
| 2. Build | Inline two-layer comments, assumptions log, non-negotiable minimums (auth via established provider, secrets in env vars, server-side validation, HTTPS) |
| 2.5. Harden | Suggested automated security tools per stack, plus online tools (SSL Labs, Mozilla Observatory) after deploy |
| 3. Audit & hand-off | Structured report, code walkthrough with stress questions, cross-AI review briefing, cool-down period, mandatory docs |
The phases are intended to scale with tier — Tier 1 (sandbox) skips most of them, Tier 3 (critical) runs all of them.
The skill loads reference files on demand. None of these are exhaustive; they are starting points.
| File | Purpose |
|---|---|
automated-security-tools.md |
Commands to run per stack, plus public web tools to check headers and TLS |
code-walkthrough.md |
12 stress questions per step of a chosen critical user path |
incident-stories.md |
Anonymised solo-builder incident write-ups intended as concrete reminders |
pause-trigger-checklist.md |
Five concrete steps with artifacts to complete during a cool-down |
senior-mode-prompts.md |
Persona prompts intended to reduce the AI's default agreeableness in critical phases |
classification-questions.md |
Follow-up questions when tier assignment is unclear |
production-checklist.md |
Per-tier checklist across seven domains |
managed-services-recommendations.md |
Service options with stated strengths and weaknesses |
cross-ai-review-templates.md |
Briefing templates for a second AI to review the build |
dsgvo-self-assessment.md |
GDPR/DSGVO self-assessment checklist (not legal advice) |
external-audit-providers.md |
Categories of paid auditors with realistic price ranges |
bus-factor-template.md |
Template for documenting single-point-of-failure handover |
sunset-plan-template.md |
Template for documenting how a project will be wound down |
- Claude Code (or a compatible AI build environment that supports custom skills)
- Optional: access to a second AI model for cross-review (Codex, Gemini, a second Claude instance)
- Optional, recommended:
npm/pip/cargoinstalled so the suggested security tools can be run
git clone https://github.com/SiliconSampl/iceberg-aware-builder.git
cd iceberg-aware-builder
mkdir -p ~/.claude/skills/iceberg-aware-builder
cp -r skill/* ~/.claude/skills/iceberg-aware-builder/
cp -r references ~/.claude/skills/iceberg-aware-builder/references
# Optional: copy default config
cp profiles/default.yaml ~/.iceberg.config.yamlOpen Claude Code and try a phrase like:
"Build me a small tool that stores incoming contact requests in a database and emails me when one arrives."
If the skill triggers, the AI should ask the four classification questions before writing any code. If it does not trigger, check that the file path is correct and that your AI environment supports custom skills the way Claude Code does.
Full quickstart: docs/quickstart.md.
v0.2.0 — experimental. The skill has not been independently evaluated. The percentage estimates in the changelog (e.g. "awareness gain 8–10%") are the author's working estimates from the design process, not measurements from controlled testing. Treat them as intent, not as evidence.
The skill is published as-is in the hope it is useful as a starting point for other solo builders. Feedback, corrections, and contributions are welcome.
- 🇩🇪 German — current master language for the skill content and reference files
- 🇬🇧 English — this README only; full English skill translation planned for a future release
- Additional languages welcome via community contributions
The skill reads iceberg.config.yaml from the project root, then from the home directory. Options include language, region preference, hosting preference, risk tolerance, preferred managed services, review requirements, and toggles for the v0.2 levers. Defaults are documented in profiles/default.yaml. See docs/configuration.md for the full reference.
- It is not legal, tax, accounting, or compliance advice. GDPR, PCI-DSS, HIPAA, and similar regimes require professional consultation.
- It is not a penetration test or security audit. It points at tools; running them and interpreting the results responsibly is on the user.
- It is not a certification of any kind. It does not produce GDPR, ISO 27001, SOC 2, or comparable assurances.
- It is not a replacement for an experienced senior engineer. The "senior mode" prompts are a prompt-engineering technique to reduce AI agreeableness; they do not give the AI senior-level judgement.
- It is not a guarantee of any outcome. Whether a build is safe to launch depends on far more than this skill can capture.
| Version | Scope | Status |
|---|---|---|
| v0.1 | Skill core, three-phase logic, default profile, German | shipped |
| v0.2 | Phase 2.5 (automated tools), walkthrough, incident stories, sharpened pause-trigger, senior mode | current |
| v0.3 | English translation of the skill itself, three industry profiles (Medical, E-Commerce, SaaS), complete worked examples | planned |
| v1.0 | Acceptance criteria met, external reviews, stable profile API | planned |
See REQUIREMENTS.md for the full specification and CHANGELOG.md for release notes.
Contributions are welcome — particularly:
- New incident stories for
references/incident-stories.md(anonymised and with permission) - Industry profiles
- Translations
- Tool corrections in
references/automated-security-tools.md - Worked examples for the
examples/directory
Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md first.
Please do not open a public issue. Use the GitHub "Report a vulnerability" feature in the Security tab, or follow the process in SECURITY.md. For vulnerabilities in software you build with the skill, follow your own incident response process — that is outside the scope of this repository.
MIT. You may use, modify, and redistribute, including commercially. There is no warranty.
This skill is provided as-is, without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, and non-infringement.
The author and contributors are not liable for any decision made on the basis of the skill's output, for any production incident in software you build with it, or for any compliance, security, or operational outcome. Responsibility for every build using this skill remains entirely with the builder.
The skill organises checklists and prompts that have proven useful in solo-builder practice; it does not replace professional advice (legal, security, accounting, data protection), and it does not by itself make any project production-ready.