Context Engineering Guide - Document Specification
Version: 1.0
Date: 2025-11-28
1. Audience
Primary Audience
- Who: Developers, technical professionals using AI tools
- Knowledge Level: Familiar with AI basics, use ChatGPT/Claude occasionally
- Pain Points: Inconsistent AI results, frustration with outputs, "AI output is unusable"
- Goals: Get better results, save time, work more effectively with AI
Secondary Audience
- Who: Managers, team leads, non-technical professionals, content creators
- Knowledge Level: Basic AI awareness, limited hands-on experience
- Pain Points: Don't know where to start, team adoption challenges
- Goals: Understand the concept, implement with team, improve personal productivity
Audience Balance
- Technical depth: 60% accessible to everyone, 40% technical details
- Examples split: Every concept has both technical AND non-technical example
- Jargon: Define terms on first use, avoid unnecessary complexity
2. Format
File Format
- Primary: Markdown (.md)
- Export targets: PDF (primary), HTML/web (secondary)
Document Structure
guide_draft/
├── 00_introduction.md
├── 01_part1_ch1_why_prompts_fail.md
├── 02_part1_ch2_good_context.md
├── 03_part2_ch3_before_prompt.md
├── 04_part2_ch4_during_after.md
├── 05_part2_ch5_tools.md
├── 06_part3_ch6_examples.md
├── 07_part3_ch7_teams.md
├── 08_part4_ch8_vibe_coding.md
├── 09_part4_ch9_wont_replace.md
├── 10_appendix.md
└── GUIDE_FINAL.md (assembled)
Length Guidelines
| Component | Target Length | |-----------|---------------| | Introduction | 600-800 words | | Chapter (average) | 2,500-4,000 words | | Section (average) | 400-800 words | | Chapter summary | 100-150 words | | Appendix | 1,500-2,000 words | | Total guide | ~24,000 words (~48 pages) |
3. Style Guide
Voice & Tone
- Voice: First person, author as practitioner ("I discovered...", "In my experience...")
- Tone: Professional but conversational, like explaining to a smart colleague
- Formality: Semi-formal, contractions okay, no slang
- Personality: Direct, practical, occasionally humorous (Borovička joke), always honest about limitations
Language Rules
- Active voice preferred: "AI processes the context" not "The context is processed by AI"
- Short sentences: Average 15-20 words per sentence
- Short paragraphs: 3-5 sentences max
- Define jargon: First use of technical term includes brief definition
- No fluff: Every sentence must add value
- Concrete over abstract: "Fix in 2 minutes" not "dramatically improved efficiency"
Formatting Rules
- Headers: Use
#for parts,##for chapters,###for sections,####for subsections - Lists: Use
-for unordered,1.for sequential steps - Code blocks: Use ``` for any code, prompts, or structured text
- Emphasis: Bold for key terms first time, italic for titles/emphasis
- Quotes: Use
>blockquote for external citations
Example: Good vs Bad Writing
Bad: "The utilization of contextual information in the facilitation of AI-based task completion is fundamentally important for achieving optimal outcomes in various scenarios."
Good: "Good context leads to good AI output. Here's why: AI doesn't know your project, your goals, or your constraints. You have to tell it."
4. Visual Elements
Diagrams Needed
| Diagram | Chapter | Description | |---------|---------|-------------| | Prompt vs Context | Ch 1 | Input divided: Prompt (10%) vs Context (90%) | | Five Components | Ch 2 | Task, Constraints, Background, Examples, Criteria | | Task Template | Ch 2 | Visual template layout | | Research Workflow | Ch 5 | Perplexity → Extract → Claude/ChatGPT | | Fix vs Fresh Decision | Ch 4 | Decision tree for when to restart | | Tool Division | Ch 5 | Perplexity/Claude/ChatGPT by task type | | Team Failure Pattern | Ch 7 | Licenses → Training → Chaos → Abandonment | | 6-Week Timeline | Ch 7 | Implementation roadmap |
Tables Needed
| Table | Chapter | Content | |-------|---------|---------| | Tool comparison | Ch 5 | Perplexity vs Claude vs ChatGPT | | Common mistakes | Ch 3 | Mistake + Fix | | Role responsibilities | Ch 7 | PO, Dev, QA, PM duties | | Success metrics | Ch 7 | What to track vs NOT track | | 10 Advices | Appendix | Quick reference checklist |
Example Box Format
Standard format for before/after comparisons:
> ❌ **Without Context:**
> "Fix the bug"
>
> **Result:** 200 lines of generic checks, none solving the problem
> ✅ **With Context:**
> "Fix permission error in ProfileView.tsx:156. User has admin role but can't edit.
> Check: Role loading, UI vs API permission logic"
>
> **Result:** Found exact issue in 2 minutes - UI checks wrong role
Code/Prompt Blocks
- Use syntax highlighting where applicable (
markdown,sql,typescript) - Include comments for complex prompts
- Show realistic examples from actual work (anonymized)
5. Citations & Attribution
Internal Citations (Author's Content)
- No formal citation needed for own articles
- Reference naturally: "As I mentioned earlier..." or "This relates to the 5-component framework"
External Citations Format
> "Quote text here"
> — **Author Name**, Platform/Source, Year
Citation Index (End of Guide)
## References
1. Karpathy, A. (2025). Twitter/X post on context engineering.
"Context engineering is the delicate art and science..."
2. Arrowsmith, G. (2025). LinkedIn post on QA bottleneck.
"QA is about to become a huge bottleneck..."
3. Martiniak, M. (2025). Survey on programmer time allocation.
Attribution Rules
- Always attribute direct quotes
- Paraphrased ideas from specific sources need attribution
- General knowledge doesn't need attribution
- When in doubt, attribute
6. Consistency Requirements
Terminology Table
| Term | Use | Don't Use | |------|-----|-----------| | Context engineering | ✓ | Context crafting, context design | | AI | ✓ | Artificial intelligence (spell out once) | | Prompt | ✓ (the instruction) | Query, request, command | | Context | ✓ (background info) | Data, information (when meaning context) | | Output | ✓ (AI response) | Result, answer (when technical) | | Session | ✓ (conversation) | Chat, thread | | Claude | ✓ | Claude AI, Anthropic's Claude | | ChatGPT | ✓ | GPT, OpenAI's ChatGPT | | Perplexity | ✓ | Perplexity AI |
Formatting Consistency Checklist
- [ ] All chapters use same header levels
- [ ] All code blocks use same style (```language)
- [ ] All examples follow ❌/✅ format
- [ ] All external quotes use > blockquote with attribution
- [ ] All lists use consistent punctuation (periods or none)
- [ ] All chapter summaries follow same structure
Naming Consistency
- "Part" for major divisions (Part 1, Part 2...)
- "Chapter" for chapters within parts (Chapter 1, Chapter 2...)
- "Section" for sections within chapters (3.1, 3.2...)
- Numbering: 1.1, 1.2 (not 1a, 1b)
7. Technical Specifications
Markdown Flavor
- Use: GitHub Flavored Markdown (GFM)
- Tables: Pipe tables supported
- Task lists:
- [ ]supported - Footnotes: Avoid (use inline attribution instead)
Special Characters Used
- ✓ (checkmark)
- ✗ (x mark)
- → (arrow)
- ❌ (red X for bad example)
- ✅ (green check for good example)
- ⚠️ (warning)
- — (em dash for attribution)
Line Length
- Soft wrap at 80-100 characters for editor readability
- No hard line breaks within paragraphs (let renderer wrap)
File Naming
00_introduction.md
01_part1_ch1_[short_name].md
02_part1_ch2_[short_name].md
...
10_appendix.md
8. Chapter Template
Every chapter follows this structure:
# Chapter [N]: [Title]
[Opening hook - 2-3 sentences that grab attention]
In this chapter, you'll learn:
- [Outcome 1]
- [Outcome 2]
- [Outcome 3]
---
## [N.1] [Section Title]
[Section content with examples]
---
## [N.2] [Section Title]
[Section content with examples]
---
## Chapter Summary
**Key Takeaways:**
1. [Most important point]
2. [Second point]
3. [Third point]
**Try This:**
[One specific action reader can take immediately]
---
*Next: [Brief teaser for next chapter]*
9. Quality Checklist for Writers
Before Writing Each Chapter:
- [ ] Read topic analysis file completely
- [ ] Review this document spec (voice, tone, format)
- [ ] Check previous chapter ending (for continuity)
- [ ] Note required visuals/examples from topic analysis
- [ ] Set target word count
While Writing:
- [ ] Follow voice/tone guidelines
- [ ] Use correct formatting (headers, code blocks, quotes)
- [ ] Include both technical and non-technical examples
- [ ] Add citations/attributions as you write
- [ ] Create visuals or mark placeholder locations
After Writing:
- [ ] Run consistency check against this spec
- [ ] Verify all planned visuals included
- [ ] Check word count is in range
- [ ] Read aloud for flow
- [ ] Verify chapter summary matches content
10. Quick Reference Card
Voice: First person, practical, direct
Tone: Professional but conversational
Examples: Always bad/good pairs with ❌/✅
Headers: # Part, ## Chapter, ### Section
Code: ```language for all structured text
Quotes: > blockquote with — attribution
Terms: Use terminology table consistently
Next Step
→ Proceed to 05_introduction_writing.md