--- name: claude-code-prompting description: Use when writing prompts for Claude Code to implement, debug, refactor, review, QA, or ship code/design work. Encodes Antoine's concise operational prompting style, scope control, templates, and verification standards. version: 1.0.0 author: Mr Han license: MIT metadata: hermes: tags: [claude-code, prompting, coding-agents, delegation, product-execution] related_skills: [claude-code, requesting-code-review, subagent-driven-development, test-driven-development] --- # Claude Code Prompting ## Overview This skill is for writing excellent prompts for Claude Code as an implementation agent. The existing `claude-code` skill explains how to operate the CLI. This skill explains how to brief Claude Code so it ships the right thing with the smallest safe diff, the right verification loop, and no strategic drift. Claude Code is not the product owner. Mr Han owns product judgment, scope, acceptance criteria, QA, and ship/no-ship decisions. Claude Code executes against a clear brief. ## When to Use Use this when: - Antoine asks for a Claude Code prompt. - We are delegating implementation, refactor, bug fix, review, design, or QA work to Claude Code. - A task needs scoped product intent translated into code-agent instructions. - Claude previously overbuilt, under-verified, or misunderstood a task. - The work touches a venture repo and needs safe constraints around deployment, secrets, data, or UX. Don't use this for: - General Claude Code CLI orchestration details — use `claude-code`. - Full architecture/spec writing before a large build — use `writing-plans` first, then this skill to turn the plan into a Claude Code brief. - Tasks better solved directly with tools or a one-line shell command. ## Core Principle A good Claude Code prompt is an execution contract: ```text what to change what not to change how to know it worked what to report back ``` Prefer compact, operational prompts. Do not dump context just because it exists. ## Antoine's Default Style Antoine prefers concise prompts with only necessary execution details. If Antoine interrupts an implementation thread and asks only for a prompt, use `references/prompt-only-redirect.md`: stop the build/QA path and deliver the pasteable prompt instead of continuing implementation. Default structure: ```text Goal Build Style Do not Verify Report ``` Use this unless the task genuinely needs more context. Avoid unnecessary boilerplate such as: - stack versions when irrelevant - repo paths when the prompt is pasted from inside the repo or the path is obvious - generic instructions like `read AGENTS.md` unless the repo convention is genuinely needed for the task - existing file names unless Claude must touch or inspect them - long strategic explanations - internal process history - generated artifact paths unless required If Antoine asks “do we need this context?”, usually remove it unless it prevents a concrete implementation mistake or safety issue. Keep safety constraints that matter: - do not expose secrets - do not send/publish/deploy - do not push/merge without approval - do not add database/storage/dependencies unless needed - do not redesign unrelated surfaces ## Prompt Length Rules ### Short prompt — default Use for straightforward features, UI additions, copy changes, small bug fixes, or scoped integrations. Shape: ```text Build [feature]. Goal: [one short outcome] Build: 1. [concrete deliverable] 2. [concrete deliverable] 3. [concrete deliverable] Style: [design/system constraints] Do not: - [scope/safety constraints] Verify: - [routes/commands/checks] Report: - files changed - commands run - results - remaining risks ``` ### Medium prompt Use when the task spans multiple files, has meaningful edge cases, touches data/model/API boundaries, or has known pitfalls. Add: ```text Relevant context: - [only facts needed to avoid wrong implementation] Acceptance criteria: - [observable success criteria] ``` ### Long prompt Use only when architecture, migrations, auth, payments, secrets, multi-service integration, or hard QA makes details necessary. Long prompts should still be structured and scoped. Length is not a substitute for clarity. ## Required Sections ### Goal One or two sentences. Describe the user/product outcome, not the implementation first. Good: ```text Add newsletter support so AgentAppStore can publish issues, collect subscribers, and promote the newsletter from the homepage. ``` Bad: ```text Modify the repo to add a bunch of newsletter stuff. ``` ### Build Concrete numbered deliverables. Each item should map to files/routes/components/tests Claude can act on. Good: ```text Build: 1. Add homepage CTA near the hero linking to `/newsletter`. 2. Create `/newsletter` landing page with signup, latest issue, and archive. 3. Create `/newsletter/[slug]` article pages that render local Markdown issues. ``` Bad: ```text Make the website better and include newsletter. ``` ### Style Include design/product constraints only if they matter. Examples: ```text Style: Match the existing dark design: muted copy, purple accent, rounded cards, responsive layout, readable article typography. ``` ```text Style: Keep the existing product language consumer-app-first. Do not make it MCP/protocol-first. ``` ### Do not This is how we prevent Claude drift. Common constraints: ```text Do not: - redesign the whole site - add database storage - add dependencies unless necessary - expose secrets or `.env` values - send emails/publish posts/deploy/push - reformat unrelated files - change public routes/APIs unless required ``` ### Verify Be specific. Claude Code should not decide what "works" means. Examples: ```text Verify: - `/` shows the CTA - `/newsletter` loads - `/newsletter/agentappstore-weekly-001-relationship-dating` loads - signup gracefully handles missing provider config - `npm run lint` - `npm run build` ``` For bug fixes: ```text Verify: - reproduce the bug before fixing if possible - add/update a regression test if practical - run the targeted test - run lint/typecheck if relevant ``` ### Report Always require a final report. ```text Report: - files changed - commands run - lint/build/test results - unresolved risks - anything intentionally left out ``` ## Templates ### Feature Implementation ```text Build [feature]. Goal: [product outcome] Build: 1. [deliverable] 2. [deliverable] 3. [deliverable] Style: [existing design/pattern constraints] Do not: - redesign unrelated areas - add unnecessary dependencies - change public APIs unless required - push/deploy/publish Verify: - [route/behavior check] - [test/lint/build command] Report: - files changed - commands run - results - remaining risks/setup ``` ### UI / Landing Page / Design ```text Build [page/component]. Goal: [user-facing outcome] Build: 1. Add [section/component]. 2. Include [copy/content blocks]. 3. Ensure responsive layout and readable mobile state. Style: Match the existing design system. Use existing components/classes where possible. Keep the diff small. Do not: - redesign the entire app - introduce a new design system - reformat unrelated files - push/deploy Verify: - check target route locally if possible - confirm mobile/responsive behavior - run lint/build Report: - screenshots or route QA notes if available - files changed - commands/results - risks ``` ### Bug Fix ```text Fix [bug]. Goal: [expected behavior] Build: 1. Reproduce or inspect the bug. 2. Identify the root cause. 3. Make the smallest safe fix. 4. Add/update a regression test if practical. Do not: - mask the error without fixing root cause - refactor unrelated code - change behavior outside this bug unless necessary Verify: - [targeted reproduction/test] - [relevant lint/typecheck/build] Report: - root cause - fix summary - files changed - commands/results - remaining risks ``` ### Refactor ```text Refactor [area]. Goal: Improve [maintainability/performance/clarity] without changing behavior. Build: 1. Inspect current patterns. 2. Refactor only [bounded area]. 3. Preserve public behavior and APIs. 4. Update tests only if needed for moved code. Do not: - change UX/API behavior - bundle unrelated cleanup - reformat untouched files - add new abstractions unless clearly justified Verify: - existing tests for this area - lint/typecheck/build Report: - behavior-preservation notes - files changed - commands/results - risks ``` ### Code Review ```text Review the current diff for correctness, security, regressions, and overengineering. Focus on: - bugs or broken edge cases - unsafe secrets/env handling - user-visible regressions - data/model/API contract issues - unnecessary complexity Do not: - leave style nitpicks unless they affect maintainability - rewrite code unless explicitly asked Report: - prioritized findings with file/line references - severity - suggested fix - anything that looks safe ``` ### PR Cleanup ```text Clean up the current PR/diff. Goal: Make the change small, safe, reviewable, and ready for final QA. Build: 1. Inspect `git diff`. 2. Remove unrelated changes/logging/dead code. 3. Fix obvious lint/type/type/build issues. 4. Keep intended behavior intact. Do not: - add new features - push/merge/deploy - rewrite the implementation unless necessary Verify: - git diff is scoped - lint/build/tests as relevant Report: - what was removed/fixed - files changed - commands/results - remaining concerns ``` ### Telemetry / Analytics ```text Add telemetry for [flow/event]. Goal: Track whether users [behavior] without collecting unnecessary personal data. Build: 1. Inspect existing analytics/event patterns. 2. Add events for [specific moments]. 3. Include useful properties only: [list]. 4. Avoid PII/secrets/raw user content. Do not: - introduce a new analytics provider - log sensitive text, emails, tokens, screenshots, or private content - change UX behavior Verify: - event code paths compile - existing analytics tests/patterns still pass - lint/build Report: - event names/properties - files changed - commands/results - privacy risks ``` ### Browser QA / Exploratory Testing ```text QA [feature/routes]. Goal: Find user-visible bugs before shipping. Test: 1. [route/flow] 2. [route/flow] 3. mobile/responsive state if possible 4. empty/loading/error states if reachable Focus on: - broken navigation - console errors - layout issues - forms not submitting/failing silently - confusing copy or CTA hierarchy Do not: - implement fixes unless explicitly asked - test unrelated areas deeply Report: - issues found with reproduction steps - screenshots if useful - severity - suggested fixes - what passed ``` ### Design Rebuild After User Rejection Use when Antoine rejects a visual direction and asks for another Claude Code pass. ```text Build [product] vN. Goal: Create a genuinely new design direction after the previous version failed. This should feel like [specific consumer artifact], not [failed premise: dashboard/command center/SaaS UI/etc.]. Context: Antoine rejected vN-1. Treat that direction as failed. Keep it intact for comparison; build vN separately. Build: 1. Add [new route/file]. 2. Add [new app/style files]. 3. Update build config for the new route. 4. Reuse existing business logic unless a tested change is necessary. 5. Add QA script for desktop/mobile screenshots and smoke tests. Product premise: [Concrete artifact-first premise. Example: the first viewport is a realistic mobile group-chat where the app posts the final decision card.] Style: [Concrete visual rules: palette, type, shape, object hierarchy, density.] Interactions: 1. [primary action] 2. [state-changing proof action] 3. [copy/share/export action] Do not: - Do not patch the rejected version visually; build a genuinely different direction. - Do not recreate the failed premise. - Do not add real external services, auth, persistence, deploys, or unsafe side effects. - Do not expose secrets, push, or deploy. Verify: - [tests] - [build] - [route loads] - [QA script saves screenshots] - [smoke-test key interactions and console errors] Report: - files changed - commands run - test/build/QA results - screenshot paths - remaining design risks ``` Useful hard line for design agents: ```text Be ruthless: if your first layout still resembles the rejected dashboard/SaaS/card-grid premise, throw it away before coding. ``` ## Context Inclusion Rules Only include context that changes implementation. Include: - required file paths if Claude would not know where to look - exact route/API names that must exist - specific existing patterns to follow - known failing command or error output - safety-sensitive facts: secrets, payments, auth, sending, deploying - user/product positioning that affects copy/UX Usually omit: - full repo history - stack versions unless version-specific behavior matters - every file that might be relevant - internal strategy notes that do not affect implementation - generated artifact paths unless they are inputs - long explanations of why the business cares ## Scope-Control Phrases Use these frequently: ```text Make the smallest safe change. Follow existing patterns. Do not refactor unrelated code. Do not redesign the whole site. Do not add dependencies unless necessary. Do not add database storage. Do not push, deploy, publish, send, or merge. Do not expose secrets or print env values. Do not change public APIs/routes unless required. If a command fails, report the exact failure and whether it seems pre-existing. ``` ## Verification Standards A Claude Code prompt should include the verification that a competent reviewer would expect. For web UI: - relevant routes load - primary CTA/action works or degrades gracefully - mobile/responsive check where possible - no obvious console/runtime errors - lint/build For API/backend: - targeted tests - integration/path check if practical - typecheck/lint - auth/error cases For data/migrations: - migration applies/rolls back if applicable - no destructive production operation - seed/sample data check - schema/types updated For email/publishing/payments: - dry-run/test mode first - do not send/publish/charge without explicit approval - secrets stay server-side - report exact provider/config needed ## Anti-Patterns Avoid prompts like: ```text Make this better. ``` ```text Here is 3,000 words of strategy. Build whatever seems right. ``` ```text Fix the site and improve design and add newsletter and maybe SEO too. ``` ```text Use the API key below in the frontend... ``` ```text Run whatever commands are needed and deploy when done. ``` Problems these cause: - overbuilding - unrelated refactors - unclear success criteria - unsafe side effects - low-signal final reports - wasted Claude turns ## Good Example: Newsletter Integration ```text Build the AgentAppStore newsletter integration. Goal: Add newsletter support so AgentAppStore can publish newsletter issues, collect subscribers via Beehiiv, and promote the newsletter from the homepage. Newsletter positioning: AgentAppStore Weekly — the weekly brief on consumer AI apps, category shifts, and what people are actually using AI for. Build: 1. Add a homepage CTA near the hero linking to `/newsletter`. 2. Create `/newsletter` with positioning copy, signup, what-you-get bullets, latest issue, and archive. 3. Create `/newsletter/[slug]` pages that render local Markdown issues with title/date/category/body and bottom signup CTA. 4. Create reusable `NewsletterSignup` component that uses Beehiiv signup/form action if configured and falls back gracefully if not. 5. Create newsletter loader with `getAllNewsletterIssues()`, `getNewsletterIssue(slug)`, and `getLatestNewsletterIssue()`. Style: Match existing AgentAppStore design: dark background, muted copy, purple accent, rounded cards, responsive layout, readable article typography. Do not: - send emails - publish Beehiiv posts - add database storage - redesign the whole site - push or deploy Verify: - homepage CTA appears - `/newsletter` works - individual newsletter issue pages work - signup does not break if Beehiiv is not configured - lint/build pass Report: - files changed - commands run - build/lint results - remaining setup needed ``` ## Good Example: Consumer Positioning UI Change ```text Update AgentAppStore homepage positioning. Goal: Make the homepage feel like a consumer AI app store, not an MCP/protocol directory. Build: 1. Rewrite hero copy around “We have an app that does what you want.” 2. Emphasize real-life tasks/outcomes over protocols/tools. 3. Keep primary CTA focused on discovering apps. 4. Preserve existing layout unless a small copy/layout tweak improves clarity. Style: Consumer-first, plain language, outcome-oriented. Avoid developer/protocol jargon. Do not: - redesign the full homepage - remove existing app data - change backend/API behavior - push/deploy Verify: - homepage builds - copy is consumer-first - no MCP/protocol emphasis in the primary hero - lint/build Report: - copy changes - files changed - commands/results - risks ``` ## Final Review Before Giving Prompt to Antoine Before sending a Claude Code prompt to Antoine, check: - Is it shorter than your first instinct? - Did you remove context Claude does not need? - Are the deliverables concrete? - Are the non-goals explicit? - Are side effects blocked? - Are verification commands/checks specific? - Would Claude know what final report to produce? - Does the prompt preserve Mr Han's product judgment instead of outsourcing strategy? ## Pitfalls 0. **Continuing implementation after Antoine pivots to a prompt.** If Antoine says “just give me a prompt,” “wait,” or otherwise switches from direct build/QA to Claude Code/Lovable delegation, stop the implementation loop immediately. Do not keep fixing tests, running builds, or explaining the abandoned path. Briefly mention any active blocker only if it changes the prompt, then provide a paste-ready prompt in Antoine’s compact `Goal / Build / Style / Do not / Verify / Report` shape. 1. **Over-contextualizing.** More context often makes Claude more likely to drift. Include only implementation-relevant facts. 2. **Skipping non-goals.** Claude Code is proactive; without boundaries it may redesign, refactor, or add storage. 3. **Vague verification.** “Make sure it works” is not enough. Name routes, commands, and expected behavior. 4. **Letting Claude decide product strategy.** Claude can implement product decisions; it should not redefine the venture direction unless asked. 5. **Forgetting side effects.** Sending emails, publishing posts, pushing code, deploying, charging users, or mutating production data must be explicitly prohibited unless approved. 6. **Including secrets.** Never put private API keys in prompts. If a provider is configured, say it is configured; do not paste values. 7. **Not asking for final report.** Without a report format, Claude may end with vague prose instead of actionable verification status. ## Verification Checklist - [ ] Prompt has a clear Goal. - [ ] Build items are concrete and numbered. - [ ] Style/product constraints are included only when useful. - [ ] Do-not list blocks likely drift and unsafe side effects. - [ ] Verify section names exact commands/routes/checks. - [ ] Report section asks for files changed, commands, results, and risks. - [ ] No secrets or unnecessary context included. - [ ] Prompt is concise enough for Antoine to paste comfortably.