Writing Strategy
The quality of AI-assisted writing depends on how you structure your requests. This chapter covers prompting strategies that produce usable first drafts, setting the stage for iterative refinement.
The Two-Phase Model
Effective AI-assisted writing follows two distinct phases:
- Generation — producing initial content through well-structured prompts
- Refinement — improving content through iterative feedback
This chapter focuses on generation. The next chapter covers refinement in depth. Separating these phases clarifies what each prompt needs to accomplish.
Anatomy of an Effective Writing Prompt
A prompt that produces a usable first draft includes:
- Context — what already exists, what comes before and after
- Scope — exactly what this piece of content should cover
- Audience — who will read this and what they already know
- Constraints — length, format, style requirements
- Examples — models of the desired output (when available)
Context
Claude Code can read your existing files, but you must direct its attention:
I'm writing chapter 4 of a Rust web framework guide.
Chapter 3 covered basic routing. Chapter 5 will cover middleware.
This chapter needs to cover request handling.
Read src/chapter-3.md to understand the established terminology
and style, then write chapter 4.
Providing context prevents contradictions and maintains consistency across chapters.
Scope
Explicit scope prevents both under-delivery and scope creep:
Too vague:
Write about error handling.
Too broad:
Write a comprehensive guide to error handling covering all
languages, frameworks, and paradigms.
Appropriately scoped:
Write a chapter on error handling in Rust web applications.
Cover:
- The Result type and ? operator
- Custom error types
- Converting between error types
- Returning errors from HTTP handlers
- Error logging
Do not cover: panic handling, async error propagation
(covered in chapter 8), or error handling in other languages.
Audience
Define the reader's starting point:
Audience: Backend developers with 2+ years of experience in
other languages (Python, Java, Go) who are learning Rust.
They understand: HTTP, REST APIs, JSON, basic error handling concepts
They don't know: Rust's Result type, ownership, or trait system
This calibration prevents both over-explanation of familiar concepts and under-explanation of new ones.
Constraints
Specify structural and stylistic requirements:
Constraints:
- Length: 2000-3000 words
- Format: mdBook-compatible Markdown
- Code examples: Complete, compilable Rust (no pseudocode)
- Headers: ATX style (#), max depth 3
- Voice: Second person ("you"), present tense
- Include: At least one diagram (described in text for later creation)
Examples
When available, provide examples of the desired output:
Follow the style established in chapter-2.md. Note especially:
- How code examples are introduced with a problem statement
- How each section ends with a brief summary
- The balance between explanation and code (roughly 60/40)
Prompt Templates
These templates provide starting points for common writing tasks.
New Chapter
Write chapter [N]: [Title]
Context:
- Previous chapter covered: [summary]
- Next chapter will cover: [summary]
- Read [file] for style reference
Scope - this chapter covers:
- [Topic 1]
- [Topic 2]
- [Topic 3]
Scope - explicitly excluded:
- [Topic A] (covered in chapter X)
- [Topic B] (out of scope for this book)
Audience: [description]
Requirements:
- Length: [range] words
- Include [N] code examples
- End with exercises or discussion questions
Write the complete chapter now.
Section Expansion
The current [section name] in [file] is too brief.
Current content:
[paste existing content]
Expand this section to cover:
- [Additional topic 1]
- [Additional topic 2]
- [Edge case or consideration]
Maintain the existing voice and style.
Target length: [range] words for this section.
Code Example Creation
Create a code example demonstrating [concept].
Requirements:
- Language: [language]
- Must be complete and runnable
- Include necessary imports
- Add comments explaining non-obvious parts
- Show both the problem and the solution
- Length: [range] lines
Context: This example appears in a section about [topic]
for readers who understand [prerequisites] but are learning [new concept].
Chapter Outline
Create a detailed outline for a chapter on [topic].
The chapter should:
- Fit within a [type] book aimed at [audience]
- Take approximately [N] pages when written
- Include [N] code examples
- Build from [starting concept] to [ending concept]
Provide:
- Section headings with brief descriptions
- Key points to cover in each section
- Suggested code examples with one-line descriptions
- Potential pitfalls or common confusions to address
Prompting for Different Content Types
Conceptual Explanations
Conceptual content explains why and how at an abstract level:
Explain [concept] for developers who understand [prerequisite]
but are new to [this domain].
Structure the explanation as:
1. The problem this concept solves
2. The core idea in one paragraph
3. A concrete analogy
4. How it works in practice
5. Common misconceptions
Procedural Instructions
Procedural content tells readers what to do:
Write step-by-step instructions for [task].
For each step:
- State what the reader will do
- Provide the exact command or action
- Show expected output or result
- Note what could go wrong and how to recognize it
Assume the reader has completed [prerequisites].
Use numbered steps with code blocks for commands.
Reference Material
Reference content provides lookup information:
Create a reference section documenting [API/feature/concept].
For each item include:
- Name and brief description
- Syntax or signature
- Parameters with types and descriptions
- Return value
- Example usage
- Edge cases or caveats
Format as a scannable list or table. Readers will look things up,
not read linearly.
Calibrating Expectations
First drafts from Claude Code are first drafts. Expect to iterate. A good initial prompt produces content that:
- Covers the requested scope
- Uses appropriate technical depth
- Follows the specified structure
- Requires refinement, not rewriting
If first drafts consistently miss the mark, adjust your prompts. If they require complete rewrites, you need better context or scope definition. If they need only polish and expansion, your prompts are working well.
The Outline-First Approach
For complex chapters, generate an outline before prose:
Before writing, create a detailed outline for this chapter.
Include:
- All section headings (H2 and H3)
- 2-3 bullet points of key content per section
- Placement of code examples
- Estimated word count per section
Review and adjust the outline, then:
The outline looks good with these changes:
- Move section 3 before section 2
- Expand the error handling section
- Add a troubleshooting subsection at the end
Now write the full chapter following this revised outline.
This two-step process catches structural issues before investing in prose.
Common Prompting Mistakes
Assuming context. Claude Code starts each session fresh. Always reference files to read or provide necessary background.
Over-specifying style. Detailed style requirements often conflict with each other. Provide an example file and say "match this style" instead of listing twenty rules.
Under-specifying scope. "Write about X" produces generic content. "Write about X covering specifically A, B, C for audience Y" produces targeted content.
Requesting perfection. First drafts are first drafts. Prompts requesting "perfect" or "final" content create pressure that doesn't improve output. Request "complete" content and plan to iterate.
Ignoring existing content. When expanding or revising, always include or reference the existing text. Claude Code cannot remember previous sessions.
Next Steps
Even well-prompted first drafts require refinement. The next chapter covers the art of pushback — the iterative questioning process that transforms adequate content into excellent documentation.