Não apenas o conteúdo. Toda a infraestrutura por baixo estava morta. Ruby 2.3, fim de vida desde março de 2019. Jekyll 2.x, sem suporte. Compass para compilação CSS, um projeto que parou em 2016. O pipeline do GitLab CI falhava silenciosamente a cada push.

Ninguém percebia porque ninguém fazia push.

A Autópsia

O CI usava ruby:2.3 do Docker Hub. Essa imagem ainda existe, congelada no tempo, baseada no Debian Stretch.

Os repositórios de pacotes do Debian Stretch foram arquivados. Todo apt-get update retorna 404. A imagem não consegue instalar nada. Nem mesmo locales.

1
2
3

docker run --rm -it -v $(pwd):/blog ruby:2.3 bash
# apt-get update
# => 404 Not Found em todos os mirrors

Esse foi o fim do Ruby 2.3.

A Correção: Migração Mínima Viável

O objetivo não era modernizar tudo. O objetivo era fazer o build funcionar de novo.

ruby:2.7 no Debian Bullseye. Repositórios funcionam. A imagem é estável.

Três coisas quebraram ao migrar de 2.3 para 2.7.

Bundler. O bundler padrão agora requer Ruby 3.2+. Fixar na versão 2.4.22 resolve:

1

- gem install bundler -v 2.4.22

FFI. As versões da gem ffi acima de 1.17 requerem Ruby 3.0+. Fixar em ~> 1.16.3 no Gemfile impede o bundler de puxar uma versão incompatível.

Pygments. A gem pygments.rb (versão 0.6.3) usa um protocolo IPC com Python para comunicar com o syntax highlighter Pygments. Esse protocolo está quebrado com Python 3.

A correção: substituir completamente pelo Rouge, um syntax highlighter escrito em Ruby puro. Sem dependência de Python. Sem IPC. O plugin pygments_code.rb foi reescrito para chamar a API do Rouge:

1
2
3
4
5

require 'rouge'

lexer = Rouge::Lexer.find_fancy(lang, code) || Rouge::Lexers::PlainText
formatter = Rouge::Formatters::HTML.new
highlighted = formatter.format(lexer.lex(code))

Nenhum post precisou de alteração. A mesma tag Liquid codeblock funciona exatamente como antes.

Desenvolvimento Local: Mais Fácil do que o Esperado

A expectativa era que Ruby 2.7 só funcionaria dentro do Docker por causa da compilação de extensões nativas (ffi, rdiscount, RedCloth).

Errado.

Com mise no Arch Linux:

1
2
3
4

mise install ruby@2.7.8
gem install bundler -v 2.4.22
bundle install
bundle exec rake generate

Todas as gems nativas compilaram sem problemas. bundle exec rake preview serve o site em localhost:4000. Docker não é necessário para desenvolvimento local.

Removendo o Peso Morto

Com o build funcionando, o próximo passo foi remover tudo que morreu enquanto o blog dormia.

Integrações mortas removidas: - Widget e botão +1 do Google+ — serviço encerrado em abril de 2019 - Google Analytics (Universal Analytics) — aposentado em julho de 2024, coletando zero dados - Botão de Like do Facebook — invasivo para privacidade, removido - Widget do Twitter na sidebar — removido da sidebar padrão

Código morto identificado mas mantido: - Flash/SWFObject no octopress.js — inerte, nenhum browser usa Flash - Modernizr 2.0 — detecção de features para browsers que não existem mais - jQuery 1.9.1 — ainda usado pela navegação, não vale remover sem reescrever

Posts ocultados: cinco posts de baixo valor (posts de teste, reposts, conteúdo datado) marcados com published: false. Não deletados — apenas invisíveis.

Frontend: Mudanças Pequenas, Impacto Visível

O tema padrão do Octopress 2 é de 2012. Um redesign completo estava fora do escopo. Mas algumas mudanças apenas em CSS fizeram diferença perceptível.

Tipografia. O font stack estava quebrado — o Sass tratava toda a declaração de fonte dos headings como uma string entre aspas. Os browsers nunca faziam match. Corrigido para usar stacks corretos de PT Sans / PT Serif com carregamento correto do Google Fonts via HTTPS.

Largura do texto. A coluna de conteúdo não tinha restrição de max-width. Em telas largas, as linhas de texto se estendiam muito além do comprimento confortável de leitura. Um único max-width: 38em no .entry-content resolveu.

Background. A textura PNG original com tiling foi substituída por uma cor sólida. A barra de navegação agora fica sobre um fundo escuro limpo em vez de uma imagem ruidosa.

Blockquotes. Adicionado cor de fundo sutil e padding adequado para uma aparência mais moderna.

Open Graph e Compartilhamento Social

O site não tinha meta tags Open Graph ou Twitter Card. Todo link compartilhado aparecia como uma URL simples sem preview.

Adicionado ao template <head>: - og:title, og:description, og:image, og:type, og:url - twitter:card, twitter:title, twitter:description, twitter:image

Esses campos são populados automaticamente a partir do front matter de cada post. Posts com campo image recebem cards summary_large_image. Posts sem recebem um card summary básico.

O que Resta

A stack ainda está longe de ser moderna. Jekyll 2 e Octopress são projetos mortos. O Compass gera vendor prefixes que nenhum browser precisa há anos. O JavaScript carrega jQuery 1.9.1 e Modernizr 2.0 em cada página.

A dependência do Compass é o principal bloqueio para uma migração ao Jekyll 4. Cada arquivo Sass usa mixins e asset helpers específicos do Compass que não existem no Sass padrão. Substituí-los é um esforço de vários dias.

Mas o site builda. O CI passa. Os posts renderizam. O conteúdo é legível.

Às vezes ressuscitar algo velho é mais rápido do que reescrever do zero.

O próximo passo é decidir se vale investir em uma migração completa para Jekyll 4 ou aceitar que essa casca de Octopress, apesar da idade, ainda funciona bem o suficiente para publicar o que importa.

Por enquanto, ele publica. Isso é suficiente.

Not just the content. The entire infrastructure underneath was dead. Ruby 2.3, end-of-life since March 2019. Jekyll 2.x, unsupported. Compass for CSS compilation, a project that stopped in 2016. The GitLab CI pipeline was failing silently on every push.

Nobody noticed because nobody was pushing.

The Autopsy

The CI used ruby:2.3 from Docker Hub. That image still exists, frozen in time, based on Debian Stretch.

Debian Stretch’s package repositories have been archived. Every apt-get update returns 404. The image cannot install anything. Not even locales.

1
2
3

docker run --rm -it -v $(pwd):/blog ruby:2.3 bash
# apt-get update
# => 404 Not Found on every mirror

That was the end of Ruby 2.3.

The Fix: Minimum Viable Migration

The goal was not to modernize everything. The goal was to make it build again.

ruby:2.7 on Debian Bullseye. Repositories work. The image is stable.

Three things broke when moving from 2.3 to 2.7.

Bundler. The default bundler now requires Ruby 3.2+. Pinning to 2.4.22 solves it:

1

- gem install bundler -v 2.4.22

FFI. The ffi gem versions above 1.17 require Ruby 3.0+. Pinning to ~> 1.16.3 in the Gemfile prevents bundler from pulling an incompatible version.

Pygments. The pygments.rb gem (version 0.6.3) uses a Python IPC protocol to communicate with the Pygments syntax highlighter. That protocol is broken with Python 3.

The fix: replace it entirely with Rouge, a syntax highlighter written in pure Ruby. No Python dependency. No IPC. The plugin pygments_code.rb was rewritten to call Rouge’s API:

1
2
3
4
5

require 'rouge'

lexer = Rouge::Lexer.find_fancy(lang, code) || Rouge::Lexers::PlainText
formatter = Rouge::Formatters::HTML.new
highlighted = formatter.format(lexer.lex(code))

No posts needed changes. The same codeblock Liquid tag works exactly as before.

Local Development: Easier Than Expected

The assumption was that Ruby 2.7 would only work inside Docker due to native extension compilation (ffi, rdiscount, RedCloth).

Wrong.

With mise on Arch Linux:

1
2
3
4

mise install ruby@2.7.8
gem install bundler -v 2.4.22
bundle install
bundle exec rake generate

Every native gem compiled without issues. bundle exec rake preview serves the site at localhost:4000. No Docker required for local development.

Cleaning Up the Dead Weight

With the build working, the next step was removing everything that had died while the blog was sleeping.

Dead integrations removed: - Google+ sidebar widget and +1 button — service shut down April 2019 - Google Analytics (Universal Analytics) — retired July 2024, collecting zero data - Facebook Like button — privacy-invasive, removed - Twitter sidebar widget — removed from default sidebar

Dead code identified but left alone: - Flash/SWFObject in octopress.js — inert, no browsers use Flash - Modernizr 2.0 — feature detection for browsers that no longer exist - jQuery 1.9.1 — still used by the nav, not worth removing without a rewrite

Posts hidden: five low-value posts (test posts, reposts, dated content) set to published: false. Not deleted — just invisible.

Frontend: Small Changes, Visible Impact

The Octopress 2 default theme is from 2012. A full redesign was out of scope. But a few CSS-only changes made a noticeable difference.

Typography. The font stack was broken — Sass was treating the entire heading font declaration as a single quoted string. Browsers never matched it. Fixed to use proper PT Sans / PT Serif stacks with correct Google Fonts loading over HTTPS.

Text width. The content column had no max-width constraint. On wide screens, text lines stretched far beyond comfortable reading length. A single max-width: 38em on .entry-content fixed it.

Background. The original tiling PNG texture was replaced with a solid color. The nav bar now sits on a clean dark background instead of a noisy image.

Blockquotes. Added subtle background color and proper padding for a more modern feel.

Open Graph and Social Sharing

The site had no Open Graph or Twitter Card meta tags. Every shared link appeared as a plain URL with no preview.

Added to the <head> template: - og:title, og:description, og:image, og:type, og:url - twitter:card, twitter:title, twitter:description, twitter:image

These are now populated automatically from each post’s front matter. Posts with an image field get summary_large_image cards. Posts without get a basic summary card.

What Remains

The stack is still far from modern. Jekyll 2 and Octopress are dead projects. Compass generates vendor prefixes that no browser has needed in years. The JavaScript loads jQuery 1.9.1 and Modernizr 2.0 on every page.

The Compass dependency is the main blocker for a Jekyll 4 migration. Every Sass file uses Compass-specific mixins and asset helpers that do not exist in standard Sass. Replacing them is a multi-day effort.

But the site builds. The CI passes. Posts render. The content is readable.

Sometimes resurrecting something old is faster than rewriting from scratch.

The next step is deciding whether to invest in a full Jekyll 4 migration or accept that this Octopress shell, despite its age, still works well enough to publish what matters.

For now, it publishes. That is enough.

AI can now generate code faster than most teams can reason about architecture.

That feels like leverage.

It is.

But it is also how structural chaos scales.

Most teams using AI today are not engineering. They are improvising at scale.

Prompt. Refine. Paste. Ship.

It works — until the system grows.

And when it grows, the cracks appear.

Architecture drifts. Decisions are forgotten. Two developers prompt differently and receive structurally incompatible outputs. The AI fills in gaps differently every time.

You don’t have a system. You have momentum.

Momentum looks like productivity. Until it turns into entropy.

AI Amplifies Whatever Structure You Already Have

Before AI, the bottleneck was typing. Now the bottleneck is thinking.

AI multiplies output. It does not multiply clarity.

If intent lives only in people’s heads, AI will guess. And it will guess differently depending on context, phrasing, or missing constraints.

That is not a model problem. It is a process problem.

The more powerful AI becomes, the more dangerous ambiguity becomes.

Large systems cannot rely on shared intuition. They require explicit intent.

This is where Spec-Driven Development becomes essential.

From Prompting to Engineering

Prompting is not a methodology.

It is a technique.

Engineering requires:

• Explicit constraints
• Preserved decisions
• Traceable requirements
• Verifiable behavior

Spec-Driven Development (SDD) shifts the interaction with AI.

The specification becomes the source of truth. Code becomes an implementation artifact.

When code generation is cheap, structure becomes the scarce resource.

Without structure, AI improvises. With structure, AI implements.

That distinction determines whether a system becomes coherent or fragile.

Preserving the “Why”: Architectural Memory

Fast AI workflows quietly erase context.

Why was this database chosen? Why was this service split? Why was this pattern rejected?

If those decisions are not recorded, they disappear.

Architecture Decision Records (ADRs) exist for this reason.

They are not documentation theater. They are short records of significant decisions, including context and consequences.

AI can generate architecture. It cannot remember intent.

If you don’t preserve the “why,” your system slowly mutates away from its constraints.

Eliminating Ambiguity: Structured Requirements

Most requirements fail because they are vague.

“The system should handle errors gracefully.”

What does gracefully mean?

Structured requirement approaches such as EARS remove that ambiguity.

Instead of aspiration, you define behavior:

WHEN a user submits invalid credentials THE SYSTEM SHALL return a 401 response and log the attempt.

This forces precision.

Precision enables:

• Predictable implementation
• Derivable tests
• Reduced interpretation
• Verifiable outcomes

In an AI context, this is transformative.

You are no longer asking the model to “build something like this.” You are asking it to implement a defined contract.

That reduces hallucination. It reduces drift. It increases reliability.

Why This Matters Now

In early prototypes, improvisation is tolerable.

In growing systems, it becomes expensive.

The cost appears later as:

• Inconsistent patterns
• Rewritten features
• Hidden coupling
• Debugging ambiguity
• Slowing velocity disguised as complexity

Startups adopting AI often believe speed is the primary advantage.

It is.

But disciplined speed wins.

Undisciplined speed compounds structural debt faster than any previous generation of tooling.

AI multiplies output. Specs multiply coherence.

If you multiply output without multiplying coherence, chaos scales.

The Strategic Question

The debate is not whether AI can write code.

It clearly can.

The debate is whether we are engineering with AI — or simply prompting it.

Are we designing systems that AI can safely operate within?

Or are we outsourcing architectural thinking to probabilistic inference?

Spec-Driven Development is not new. But in the AI era, it is no longer optional for serious systems.

If your team is building beyond prototypes, this question matters.

Are you engineering structure first?

Or hoping coherence emerges later?

References

• Michael Nygard, Documenting Architecture Decisions
• Alistair Mavin et al., EARS: Easy Approach to Requirements Syntax
• ThoughtWorks, Technology Radar
• BMad, BMad Hatter Agent Method
• Kiro, Spec-Driven Development IDE
• CC-SDD, Claude Code Spec-Driven Development

This script was based on dreamgit.sh from dreamhost wiki.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

#!/bin/bash

# set -x ## debug
SERVER_REPOS="/path/to/repos.git"
LOCAL_REPOS="/path/to/Repositories"
DREAMGIT_DOMAIN=user@host.domain.com


cd $LOCAL_REPOS
ssh $DREAMGIT_DOMAIN 'mkdir -p '$SERVER_REPOS/$1'.git && cd '$SERVER_REPOS/$1'.git && git --bare init'
mkdir $1
cd $1
git init
git remote add origin ssh://$DREAMGIT_DOMAIN$SERVER_REPOS/$1.git
touch .gitignore
git add .
git commit -m 'New repository created'
git push origin master
echo "
[branch \"master\"]
  remote = origin
  merge = refs/heads/master" >>.git/config
echo "New repository '$1' was created and iniatialized on $DREAMGIT_DOMAIN$SERVER_REPOS/$1.git"

#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################
#####################################################################################################