CLAUDE.md — Working with slavikdev.com

About the Author

Slavik Shynkarenko — Head of Platform Engineering at AutoScout24 & Trader Inc., managing 40+ engineers across Germany and Canada. Builder, leader, and creator of the Miri programming language. The blog covers three topics: Leadership, Software Engineering, and Miri (a GPU-first programming language Slavik is building in Rust).

Project Overview

Stack: Jekyll static site on GitHub Pages, AMP-compliant
URL: https://slavikdev.com
Fonts: Source Serif Pro (body), Source Sans Pro (headings)
Config: _config.yml
Layouts: _layouts/ — default.html, post.html, page.html, category.html
Includes: _includes/ — head.html, header.html, footer.html, share.html, analytics.html
Styles: _includes/css/styles.scss (inlined for AMP), _sass/ for partials
Posts: _posts/ — subdirectories per topic (technical-leadership/, miri/), drafts in _posts/_drafts/
Images: assets/images/posts/ for article images, assets/images/categories/ for category pages
Category pages: Root-level HTML files (leadership.html, software-engineering.html, miri.html)

AMP Constraints

This site is AMP-compliant. This is non-negotiable. When writing or modifying templates:

All CSS must be inlined in <style amp-custom> (no external stylesheets)
Use <amp-img> instead of <img>. Always include width, height, and layout="responsive" attributes
No custom JavaScript except through <amp-script> components
No <img>, <video>, <audio> — use AMP equivalents
Social sharing uses <amp-social-share>
Comments use <amp-iframe> for Disqus embed

Running Locally

bundle exec jekyll serve

Writing Style Guide

Voice: Experienced Practitioner, Not Lecturer

Write like someone who has led teams, shipped products, made mistakes, and learned from them — and is now telling you about it over a drink. Not pitching, not lecturing, not performing expertise. The credibility comes from specifics and honesty, not from authority claims.

Core qualities:

Conversational and direct. Say what you mean. No hedging, no filler, no corporate padding. “Leverage,” “synergy,” “at the end of the day” — these are banned.
Confident but grounded. Share strong opinions (“Rust is an absolute masterpiece of engineering”) and back them with personal experience, not appeals to authority. Acknowledge alternatives honestly.
Self-deprecating without self-pity. Freely admit mistakes, doubts, procrastination. Use humor to keep it light (“a masterclass in productive procrastination”). The vulnerability earns trust; the forward motion keeps momentum.
Honest about emotions when they matter. Don’t shy away from burnout, feeling lost, or personal difficulty — but state it plainly and move forward. No dwelling, no melodrama.

Sentence Craft

Alternate sentence length. Short punchy statements for dramatic or emotional beats (“I realized I had completely lost myself.”). Longer flowing ones for explanations and narrative. The rhythm matters — monotonous sentence length kills engagement.
Em dashes freely for asides, pivots, and mid-sentence personality injections.
Parenthetical asides for color, humor, or self-aware commentary (“which was an adventure in itself, considering the language had evolved significantly since I last touched it a decade ago”).
Italicized rhetorical questions as narrative turning points: Why couldn’t there be a language as ridiculously fast as C++ but as joyfully easy to use as Ruby?
Contrast and tension as a device. Juxtapose opposites for impact: “On paper, my career was soaring. But behind the scenes, my personal life was fracturing.”

Typography

All article body text must use proper typographic characters, following publishing best practices. Frontmatter, code blocks, and inline code are exempt — they must keep ASCII characters.

Curly (smart) quotes, not straight quotes. Use ' ' for single quotes and " " for double quotes. Straight ' and " must never appear in body prose.
- Apostrophes use the closing single quote: ' (e.g. don’t, it’s, engineers’).
- Opening quotes follow whitespace or start of line; closing quotes precede punctuation or whitespace.
Ellipsis character. Use … (U+2026), not three periods ....
Em dash. Use — (U+2014) with no surrounding spaces for parenthetical breaks and pivots. Already established in the style guide.
En dash. Use – (U+2013) for ranges (e.g. “2024–2025”, “pages 10–20”). Not a hyphen.
Hyphen. Use - only for compound modifiers (“async-first”, “real-time”) and hyphenated words.
Multiplication sign. Use × (U+00D7) instead of the letter “x” when expressing dimensions or multiplication (e.g. “700×400”).

Where these rules do NOT apply:

YAML frontmatter (must use straight quotes for valid YAML)
Fenced code blocks (between ` markers)
Inline code (between backtick ` markers)
HTML tags and attributes
URLs and file paths

A formatting script is available at scripts/format-typography.rb to convert existing posts. Run it with:

ruby scripts/format-typography.rb            # all posts
ruby scripts/format-typography.rb --dry-run  # preview changes
ruby scripts/format-typography.rb _posts/my-post.md  # single file

Structure & Pacing

Lead with a hook, not a thesis. Open with a question, a scenario, a confession, or a bold claim — something that makes the reader want the next paragraph. Never open with “In this article, I will…”
Section headers should have energy. Use tension, metaphor, or emotional framing: “Losing — and Finding — Myself” not “Personal challenges in 2024.” Headers are promises — make them interesting.
Each section ends with forward momentum — a spark, a realization, a decision that propels into the next section. Not a summary of what you just said.
Technical details woven into story, never lectured. Mention the compiler pipeline, GPU architecture, or OKRs naturally as part of what you were thinking or doing — not as a sidebar explanation for the reader.
Show the thought process. Explain why you changed your mind, what made you pivot, how your assumptions were wrong. The journey is more interesting than the conclusion.

Content Balance by Topic

Platform Engineering articles:

The primary professional content pillar. The audience is engineering leaders and senior engineers navigating platform strategy, team structure, and tooling decisions.
Tone model: “Platform Engineering Trends 2026.” Dense, opinionated, authoritative. Short declarative paragraphs. Minimal fluff. Every sentence earns its place.
Lead with your position and experience — “As Head of Platform Engineering at AutoScout24 and Trader Inc.” — to establish credibility immediately, then let the content do the rest.
Structure around ideas, not formulas. Each section should have its own natural shape. Avoid repeating the same pattern (problem → explanation → example → recommendation → reflection) across every section. Some sections are an argument, some are a comparison, some are a story. Let the content dictate the form.
Name real tools, frameworks, companies, and metrics (Backstage, ArgoCD, Kubernetes, OKRs, “54% reduction in high-severity incidents”). Specificity is what separates expert content from generic advice.
Acknowledge trade-offs explicitly. Platform Engineering is fundamentally about trade-offs — local freedom vs. global throughput, customization vs. maintainability, build vs. buy. Don’t just prescribe the “right” answer; explain what you’re giving up and why it’s worth it.
When giving practical advice, weave it into the argument. Don’t box it into “Actionable Recommendations” sections at the end of every heading — that pattern becomes repetitive and makes the article feel like a textbook.
Ground points in real anecdotes from AutoScout24, acquisitions, or previous roles. But keep anecdotes tight — a sentence or two of context, not a full story. The Platform Engineering Trends article does this well: “At AutoScout24, our paved-path compute is Kubernetes-based” — factual, brief, authoritative.
Strong closings. End with a clear, memorable takeaway — not “reflect on your approach” or “what’s next for you?” The Trends article nails this: “The direction of travel is clear. What remains is how deliberately leaders choose to move.”

Leadership / management articles:

More structured than Platform Engineering pieces — numbered lists and sub-headers for actionable strategies are fine here, since managers often scan for applicable techniques.
Still ground every point in real experience. “At one company I worked with…” is fine, but naming AutoScout24 or giving a specific outcome is better.
Authoritative and direct, not tentative: “Platform Engineering has crossed a threshold” not “I think maybe Platform Engineering is becoming more important.”
Balance collaboration/soft-skill topics with enough concrete specifics that the reader walks away with something actionable, not just inspired.

Miri / technical articles:

60% personal story / 40% technical substance. The narrative is the vehicle; the tech is the payload.
Let the reader feel what it’s like to build a compiler, fight the borrow checker, make hard trade-offs.
Acknowledge the ecosystem honestly — mention alternatives by name, credit what they do well, explain why you went a different direction.
AI/tools are part of the story naturally. Describe your evolving relationship with them as a journey, not an endorsement.
Code examples should be minimal and purposeful — illustrate the concept, don’t dump implementation.

Software Engineering articles:

Practical, opinionated, concise.
Take a clear stance and defend it with reasoning and examples.
It’s okay to be provocative (e.g. “Do we need unit tests?” — the answer isn’t a safe “yes”).

What to Avoid

Bullet-heavy listicles as the primary format. Lists are fine for specific recommendations, but the article shouldn’t be a list.
“Actionable Recommendations” boxes at the end of every section. Weave the advice into the narrative instead.
“So, what’s next for you?” / “Take a moment to reflect” calls-to-action at the end of every section. One closing reflection per article is enough.
Repeating the same structural pattern across every section (problem → explanation → example → recommendation → reflection). Vary the rhythm.
Over-explaining concepts to prove expertise. The reader is a peer, not a student.
Humble-bragging disguised as vulnerability.
Generic motivational conclusions. End with something specific and real.
Detached, third-person analysis tone. This is a personal blog, not a whitepaper.

Language & Word Choice

Vivid, casual metaphors. “gathering digital dust,” “floating through a sea of ideas,” “alien hieroglyphics.” Prefer unexpected imagery over cliches.
Colloquial energy. Words like “unhinged,” “ridiculously,” “unapologetically cool,” “yelling at me.” The register is smart-casual, not formal.
No corporate-speak. No “leverage,” “synergy,” “ecosystem” (unless literally about tech ecosystems), “holistic,” “paradigm shift,” “best-in-class.”
Contractions are fine. “Don’t,” “isn’t,” “you’re” — this is a blog, not a journal paper.

Post Frontmatter Template

Every post must include this frontmatter structure:

---
layout: post
title: 'SEO-optimized title (60-70 chars ideal)'
description: 'Meta description for search engines (150-160 chars max). Include primary keyword naturally.'
h1: 'Display heading — can be longer/different from title'
comments_enabled: true
jsonld: post
image:
  url: 'posts/image-filename.jpg'
  width: 700
  height: 470
topic: 'Leadership'           # or 'Miri' or 'Software Engineering'
topic_url: /leadership/       # or /miri/ or /software-engineering/
tags:
  - primary-keyword
  - secondary-keyword
  - topic-tag
breadcrumbs:
  -
    title: 'Topic Name'
    url: /topic-url/
---

Frontmatter Rules

title is used for SEO (<title> tag, OpenGraph). Keep it under 70 characters. Include the primary keyword near the front.
h1 is the visible heading on the page. Can be longer and more descriptive than title.
description appears in search results and social cards. 150-160 characters max. Write it to compel clicks — not just summarize.
image.url is relative to assets/images/. Featured images should be 700px wide.
tags should be lowercase, hyphenated. Include the topic tag (e.g. leadership, miri, software-engineering).
File naming: YYYY-MM-DD-slug-matching-permalink.md inside the appropriate _posts/ subdirectory.

SEO Best Practices

On-Page SEO

One H1 per page (the h1 frontmatter field). Use H2 and H3 for sections — never skip levels.
Primary keyword in: title, h1, description, first 100 words of the article, at least one H2, and the URL slug.
Meta description: 150-160 characters. Should read like a compelling reason to click, not a dry summary. Include the primary keyword naturally.
Internal linking: Link to other articles on the blog where relevant. Use descriptive anchor text, not “click here.” Example: [shared vision](https://slavikdev.com/crafting-a-vision-for-platform-engineering/).
URL structure: Clean, keyword-rich slugs. The permalink config /:title/ handles this — so make the filename slug meaningful.
Image alt text: Descriptive, keyword-relevant alt text on every <amp-img>. Not keyword-stuffed, but genuinely descriptive.

Content SEO

Target a clear search intent for each article. Ask: what would someone search to find this? Write the article that answers that query better than what’s currently ranking.
Article length: Aim for 1500-3000 words for leadership articles. Miri articles can go longer (3000-5000) since they’re deep technical content.
Use the full keyword spectrum: Include synonyms, related terms, and long-tail variations naturally. Don’t force exact-match keyword repetition.
Structured data is already handled by the JSON-LD includes (blog-posting.json, tech-article.json). Don’t modify these unless the schema is genuinely wrong.

Technical SEO (Already Configured)

The site already has: canonical URLs, OpenGraph/Twitter Card meta, JSON-LD structured data, sitemap.xml (via jekyll-sitemap), RSS feed, breadcrumb schema, AMP compliance. Don’t break any of these when editing templates.

Working with the Codebase

Adding a New Article

Create a featured image (700px wide) in assets/images/posts/
Create the markdown file in the appropriate _posts/ subdirectory with correct date-slug naming
Include full frontmatter (see template above)
Write the article following the style guide
Verify locally with bundle exec jekyll serve

Editing Layouts & Templates

All layouts extend default.html which extends compress.html
CSS changes go in _includes/css/styles.scss or the relevant _sass/ partial
Remember: all CSS is inlined for AMP. Total CSS must stay under AMP’s 75KB limit.
SCSS variables are in _sass/_config.scss

Adding a New Category/Topic

Create a root-level HTML file (e.g., new-topic.html) with layout: category and the appropriate tag
Create a subdirectory in _posts/ for the topic
Add a category image to assets/images/categories/
Update navigation if needed in _includes/header.html

Images in Articles

Use AMP-compliant image syntax:

<amp-img
  width="700"
  height="400"
  layout="responsive"
  src="https://slavikdev.com/assets/images/posts/image-name.jpg"
  alt="Descriptive alt text">
</amp-img>

For secondary/inline images, add class="secondary-image" and wrap in a centered div if needed.

Code Blocks

Use fenced code blocks with language identifiers. Jekyll uses kramdown with Rouge for syntax highlighting. Supported and commonly used: js, miri, yaml, bash, rust.

Content Principles

Every article should teach something real. Not rehash conventional wisdom — offer a genuine insight, a hard-won lesson, or a technical deep-dive that the reader can’t easily find elsewhere.
Credibility through specifics. Name the company, the tool, the metric, the outcome. “We reduced high-severity incidents by 54%” beats “we improved reliability significantly.”
Respect the reader’s time. If a section doesn’t add value, cut it. If an idea can be said in one paragraph, don’t stretch it to three.
One article, one clear thesis. The reader should be able to state what the article was about in one sentence after reading it.