Alex Oliveira

Code agents in 2026

2025-12-16T14:00:00+00:00

I’ve been using Claude Code as my primary coding assistant for a while now. More recently, I managed to start a flywheel effect and have the AI code full solutions with as little interventions as possible by leveraging subagents and skills to prevent context rot and keep agents under strict control.

This guide distills the patterns that have worked for me.

Patterns

Be hyper specific: For great results, your prompt inevitably needs to be long and complete because agents need to know exactly what you want. Claude follows instructions literally, so vague requests get vague results.

It follows that if you’re going to invest in great prompting at every checkpoint, you will need to save your prompts. Not like in the old days, where we kept saved snippets around as copy/pasta. Instead,

leverage CLAUDE.md: have a great, general memory file you can reuse. You can copy my universal coding prompt if you want a system prompt that works well across the board.
use skills: these are recipes that agents pull based on what they’re doing.

I’ve had great experience using a Voice-to-Text app like Aqua. Aside from outputting words faster than typing, I find myself rambling a bit longer, which ends up sharing more of my intent with the AI. Uncertainties also come out and help inform the planner on approaches.

State your intent: A single sentence explaining what the output is for changes how Claude approaches the task. “I plan to build X on top of this feature” or “This app is low load so don’t care about optimizations” are useful information. The purpose shapes approach, depth, and what gets emphasized during its thinking.

One example: my personal app has to send a notification via Telegram, and later WhatsApp. Claude’s first approach was calling a TelegramClient straight from a business class. Not great, as it will force refactoring and rework later. By stating that I wanted a second channel in the future and to use an adapter pattern, it (1) added a MessagingChannel class as interface between Telegram and the business domain, and (2) updated the documentation to state how the architecture should look like.

Examples are instructions: When you provide a sample, Claude treats it as a template. This works both ways, and a sloppy example produces sloppy output. Be deliberate about what you show.

A good example is my code-review skill. The file has precise examples on output format and real-world scenarios it should look out for.

Chunk the work: Long tasks work better as a series of checkpoints than as a single “do everything” request. The longer the AI works in one go, the higher the chance it will stray away from the original intent. Ask for one piece, verify it, then continue. The model stays more coherent and you catch mistakes early.

Overall, what works for me is establishing a doc with a general architecture (as CLAUDE.md) that guides the whole operation, and a product doc that explains the app’s rationale (e.g docs/prd.md). From that high level, don’t descend to the “create this button” level, but rather state your end goal for the feature and ask it to break it down (e.g “I want the app to fetch calendar events once a day and store in a new table”). Claude’s Plan Mode is great for breaking down that problem and creating to-dos for execution.

A sophisticated approach is (1) asking Claude Code to break down that docs/prd.md into tasks and put them somewhere like todo.md (if you don’t yet, use my skill, working-off-of-todo-files). Then tell Claude to work on the next task in Plan Mode. Review the plan, ask for specifics e.g method names and what tests will be written, and then let it roll.

Start a flywheel effect

Have an end-to-end protocol and see agents working on their own for longer.

If you could force Claude to self-correct based on a predefined quality heuristic, it would work for 30-60 minutes on its own and still produce good quality code.

The main challenge is the probabilistic nature of agents. They may or may not produce what you expect. You have to nudge and push them in a particular direction, like a junior developer.

The loop that worked great for me follows these steps:

One task at a time: have a todo.md file, and tell the agent to work on the next one only
Plan Mode: get a detailed plan for that task.
Test skill: make sure the agent writes great tests, they are your deterministic point of reference, effectively your acceptance criteria.
Let it cook: let the AI work with Auto-accept Edits on.
Code review: let the agent review its own generated code using a skill you have defined. It will self-correct.
Run tests: this is the determinism phase, and will ensure the agent fixes its own problems.

I had sessions where the agent worked on its own for 30-60 minutes and the final result was acceptable. The elements that finally made it possible in 2025 were (a) Anthropic’s Opus 4.5, (b) the testing skill and running specs, and (c) a code review flow.

My rspec-rails skill guides the agent towards better tests, ones that use distinct context blocks and make it think further about dependencies. The test failures serve as point of reference for the agent to self-correct.

The final trick is a review process at the end. For Rails codebases, I have this code-review skill that works wonders.

Skills: Recipes as prompt

Remember when you had to save long prompts to reuse later? Skills solve that. They load only when needed, automatically. Think of them as specialized tools you pull out for specific jobs.

As your agent executes during those 30 minutes, it will figure out whether there’s any relevant skill to be used, and will pull those automatically into context. It will follow your instructions more effectively without you having to write an endless initial prompt.

They differ from commands because you don’t need to trigger them yourself.

Skills are how my agents stopped producing slop. My most useful skills right now are: writing tests; reviewing its own code; working off of todo.md; practicing TDD when a bug is found.

Subagents: Fighting context rot

This is where things get interesting. Subagents run in their own context, do their work, and return results to the main agent, keeping the main conversation clean.

Why does this matter? Context rot. The longer a conversation goes, the more diluted your instructions become. By offloading exploration, research, and specialized tasks to subagents, you keep the main thread focused. Realistically, as you approach 40% of the context window you should start seeing substantial loss in effectiveness.

All you have to do is write, “using subagents, do X”. My code-review skill tells the agent to trigger subagents to perform those reviews. All files are open and tests run by that subagent, and none of those tokens go into the main context.

Examples of when I spawn subagents:

exploring codebase: “Read all files from bin using subagents and give me a summary”
running tests: “Run and fix tests using subagents”
researching documentation: “read docs/ using subagent and figure out which one is useful for this problem”

Parallelism

When a task takes 2-5 minutes, that’s when flow is the worst. You lack time to look elsewhere, you can’t spin up two terminals side-by-side and work in parallel productively. If you go check Slack and get back later, much more time has passed. Wasted time.

When the average lifecycle crosses 20 minutes, though, things change. Suddenly you’re able to work on multiple projects or tasks at once because you can focus for longer. In my estimation, that moment has arrived and only much later the industry will feel its impact.

On the one hand, regular developers will keep copying/pasting AI code between apps, or praying to the church of the <tab><tab><tab>. Junior developers will struggle to make it into the market because they lack judgment necessary to review great code. Interviews will be less about algorithms and knowledge, and more about critical thinking and abstract problem management.

On the other hand, advanced engineers will figure out how to tame AIs and work on 4-5 tasks or projects in parallel. They will pioneer a new role that mixes skillsets from PMs (managing requirements), managers (communicate vision unambiguously) and architects (judging technical plans end-to-end). They will be in another league.

The tricks above are the seeds to ensure agents can run on their own, with as little handholding as possible. I also believe strongly that the determinant element to prevent the house of cards from falling is automated tests. They represented the guardrails in the past, and will become even more important.

Protip: I get distracted when agents are running, and notifications don’t work for me. I found a killer setup that holds my focus: when the agent finishes, it triggers a hook that makes my Tmux pane’s background orange. It’s ugly as hell, but my eyes can’t simply not look at it. This has kept me in the flow while working in parallel.

Opus 4.5 pushed us into a land of rarer hallucinations, especially when it’s kept under a tight leash with an iterative process. Agents still won’t produce what you expect, though, without hyper-specific prompts and context rot prevention.

For those who want to maximize their effectiveness, a setup for parallel execution is as close as we can get to the agent’s holy grail.

Five Days on the Kumano Kodo

2025-10-03T07:00:00+00:00

It’s 9:00 am, September 29, Takijiri-oji (滝尻王子). The river runs shy between the rocks and mirrors the forest, with mountains rising behind it. I hear a faint bell ringing somewhere up the slope while two hikers pass and disappear into the cedar shade. I set a boot on a stone step braided with roots, take a long breath, and let it out.

People have walked the Kumano Kodo (熊野古道) hills for a thousand years. I came for five days of walking and a mental reset I couldn’t quite define. I don’t know yet that the stairs will go on for hours, whether I’ll encounter bears, or if I’ll arrive before sunset. I only know the pack sits on my back, my breath is steady, and my eyes aim at the trail.

“Is one of these the one we’ll climb”? I wonder. When our Airbnb host dropped us at the trailhead this morning, the mountains looked imposing and impenetrable, steep like a wall. Last night at dinner, another guest who had walked from Takijiri-oji to Takahara (高原) tried to dissuade us from starting here. They vehemently argued we should skip this section. I sipped wine and shrugged: “where would the fun be in that? I traveled around the planet for this”.

A shy river, mountains ahead

A total reset

Disconnecting from routine

The idea of a total reset had been circling my mind for quite some time, a need to disconnect from routine, tune out the noise, and reconnect with my own thoughts. The Kumano Kodo trails in Japan felt like the right backdrop for that experiment. I assumed the effort would be rewarded by shrines. I didn’t know yet that the walk itself would become the destination, and each step a small arrival.

For thousands of years, these trails have guided pilgrims toward sacred temples and connected walkers in search of meaning, or just adventure. While walking those paths for five days in search of the latter, I may have stumbled upon a little of the former.

The absence of Switzerland’s turquoise lakes or the dramatic Alps of France meant the landscape wouldn’t steal the spotlight, it would walk beside me instead, like a quiet companion. Yet, by the final day, all I wanted was to start again. Those soft, green mountains held more beauty than I expected.

From the start, this had to be a distraction-free walk. Even when the idea was still forming, it was clear that I wanted full immersion: no social media, no podcasts, no music. Just the here and the now. No autopilot, only awareness.

Day 1: Takijiri-oji to Chikatsuyu

Finding the rhythm of the path

The walk starts off climbing a staircase with steps twice the regular height, and I feel a slight burn in my thigh. It’s just a warm up. At first, my wife and I are enchanted by the beauty and historical significance of this place. “Lots of photography opportunities”, I think. You don’t see rocky stairs intertwined with tree roots like these anywhere.

The staircase never stops. We’re ten, thirty, fifty minutes in and it’s an endless, tough ascent. After 656 feet of elevation (200 meters), my body is protesting loudly, “what the hell are you doing, Alex?”. The initial climb is sudden, dramatic and slow, but a smile escapes me when I remember Tom ascending to heaven in an infinite staircase.

After a while, the stairs morph into marble-sized little rocks. Every step is a meticulous task of positioning the foot properly, as if my ankles are dancing. The physical intensity is only matched by the mental challenge of choosing where to tread among the infinity of roots. Think of tetris, but with your feet.

Light rain needles through the canopy, forming dots on my forearms. “Uh oh”, I exhale, hoping to stay on a dry path.

After a brutal initial ascent, we reach a flat section where we can accelerate and keep a better pace. The watch displays 10:42am and 1,040 feet of elevation gain (317m). After 3.44km, heart rate drops to 111bpm. The knot in my throat disappears and I can breathe again. The rain stopped and I realized it’s been a while since I thought about it.

A flat section, a relief for the glutes

A small detour in the woods to the Iimoriyama observation deck (飯盛山展望台)

We are rewarded with astonishing views

Half an hour later, we step on asphalt and arrive in a small village with an open space where walkers rest. The gradient horizon reveals mountains stretching further away, alternating like a folder cabinet containing ancient history. The view is the reward.

The trail from here bifurcates on to Takahara (a short 1km trip), or to Chikatsuyu for another 8.5km, our original plan. The place has toilets, seats, tables, a vending machine full of sold out drinks, a cute cat, and pay phone available. We admire the distance for a good 30 minutes, absorbing the significance of where we are.

Strategic point of sale for walkers. Coffee tastes fresh.

The clock displays 12:38pm. The forecast shows rain incoming again, and our legs already climbed 1,686 feet (514 meters). We do have time to walk to Chikatsuyu, we just need to keep a decent pace and to reach the guesthouse we’ll be staying at before 5pm.

We ponder on the alternative of taking a bus from here because if it starts raining, the lime stones get really dangerous. I sip my coffee, bought from a local tent shop, and shrug, “where would the fun be in that? We travelled around the planet for the challenge”. And so we decide to continue.

After resting for half an hour, we get back into the trail to Chikatsuyu and meet another steep ascent. This time, it’s not a staircase, but a flat, sloped surface that makes your shin muscles burn. 15 minutes in and it feels extremely tiresome.

The tiredness isn’t the problem (I expected exhaustion, so I won’t dwell on that). It’s the brain asking how long until it gets easy, or how long until the pain stops. That’s not really useful thought, though. First, we have barely started, so c’mon already. Second, it’s a waste of mental energy to ponder about things you can’t change, or the path that has been planned a long ago. Where we are now is just a zone of discomfort and the right thing to do is to push the body forward. That’s the focus that matters.

***

Our hectic arrival in Japan after a 10-hour, sleepless flight added a layer of complexity and mental exhaustion to this walk. When we landed in Tokyo, we had about 24 hours to go through immigration, travel another 12 hours by train, sleep, pack, buy gear, and figure out where to get bear spray. Oh boy, don’t even get me started on the bear spray adventure.

In Tanabe the evening before the walk, our taxi driver ignored our directions and drove us somewhere else, stressing us out and making us late to our Airbnb. We put our host on the speaker at some point, and even he got mad at the driver for ignoring him and not knowing basic information about routes.

At some point, as we rode uphill on dark roads, I conceded the possibility that he’d drop us in the middle of nowhere. “How am I telling my wife we’re sleeping by the road tonight”? I don’t understand Japanese, but I do understand a taxi driver yelling on his phone to an unknown person, “something something gaijin, something gaijin”. I learned from the series Shogun that gaijin means foreigner, and the word is often used in a derogatory way. Later, our host explained the driver was quite elderly, which helped explain the confusion.

In the end, everything worked out fine, but when we were dropped at the trail the next morning, some of the adrenaline was still there. It felt like parachuting into a combat zone. It took a while of walking to finally cool down and get into the mental flow we came here for.

This section of the walk is a grind, and my back hurts. It’s fine, and I was expecting that, expecting it earlier. During my preparation for this walk, my back has been bothering me quite a lot. For some reason it hadn’t hurt for a while, but now it does again, and this heavy backpack isn’t helping. It weighs roughly 15kg.

I brought a laptop to unload my camera photos and write. The ritual involves working hard with my legs during the day while my mind wanders aimlessly, and then write about the journey in evening while my legs rest. That should keep my mind engaged during these 5 days.

What alleviates my back pain a bit is engaging my core, like when someone’s gonna punch you and you flinch. As I brace my abs and my belly tightens, I feel a relief in my spine. Overall, we’re following the plan as intended, but I guess at this point, the decision is picking the less annoying annoyance, pain or effort.

A mile and a half into this section to Chikatsuyu, after beautiful forests and trails, we are welcomed by an incredible lake reflecting the trees and the sky like glass.

A still lake appears and mirrors the hillside so cleanly it looks edited

I’m still trying to grasp the beauty and mystery of this place, and words escape me. I ponder the countless people who have walked these paths before, all their experiences and the memories stacked together. Yet, here I am.

In the 12th century, retired Emperor Go-Shirakawa walked the Kumano Kodo thirty-four times. Emperor Go-Toba twenty-eight. It was while walking these trails in 1160 that Taira no Kiyomori got word that his opponent, Minamoto Yoshitomo, had taken the opportunity to stage a coup in Kyoto (京都).

I’m not a pilgrim, at least not by any formal measure. I came for five days and a reset I couldn’t name, to walk until the noise thinned out. The sense of gratitude just for being able to start the trail, let alone finish it, fills my chest. To be able to touch a little of this history is a privilege I wish all my friends could experience.

The wrist watch shows 2:57pm and we’re two thirds into the trail to Chikatsuyu. A total of 05h06 so far, 2,982 feet of elevation gained (909m) and 11km.

When comparing to the beginning of the trail, this section feels like the hardest. Contrary to what the Tanabe Prefecture’s website says, that Takijiri→Takahara is harder than Takahara→Chikatsuyu, I found the opposite to be true. Well, I could also attribute that to the weight, energy and aggregated tiredness, which feels like it has compounded a lot by now.

My left knee hurts, so I resort to using my hips more for walking than the knees, to alleviate the pain through the endless ups and downs. Some sections almost force us to use our hands to climb without falling. It just keeps going on and on and on.

My back pain got worse, and no amount of core engagement is helping, but according to my calculations we’re towards the end of today’s trail, hopefully soon we get to the section in which descends all the way to Chikatsuyu.

When we finally get to the descent section, an annoying pain two inches below my knee starts. It’s insistent like a tip of an arrow against my shin, but it’s fine. It’s also understandable, a probable weak muscle I ignored in the gym. A muscle that is never used until you jump into millennia-old hike, like the Kumano Kodo.

We suddenly spot Chikatsuyu on the horizon, in between the trees. My eyebrows rise, my chest inflates and I exhale a sigh of relief. The sun illuminates the mountain tops and we speed up our feet to get to the village before it gets dark.

We enter the village by what looks like a backdoor, coming in from the mountains. The clock shows 5:40pm, twenty minutes before the only grocery store closes. We rush our feet and get in just in time.

When I put the heavy backpack on shopping cart, my back smiles, a smile of relief. We buy instant noodles for dinner, along with desserts we have no idea about. We want a little surprise. Eggs and bread for breakfast the next morning aren’t forgotten.

At the guesthouse, shower, dinner, resting. The body pulsates a mix of soreness and satisfaction. The walk was tough but rewarding. I can’t wait for tomorrow.

Time for the sleep of the gods.

Chikatsuyu

Day 2: Hosshinmon-oji to Hongu

Shrines, silence, awe

We wake up in Chikatsuyu. This is the first proper morning in god-knows-how-long. Four days, I think. A slow morning, to sit down and chill without a burning need to get somewhere. The last night in the United States I could barely sleep 2-3 hours, thinking non-stop about the trip, only to get up at 5:30 to head to the airport.

So, yes, we’ll take our time. I step outside, take the deepest and longest inhale you can imagine, and stroll the village under bright blue skies to buy black coffee. I head back to prepare scrambled eggs and toast. Pack things and close the electronic door behind us.

Time to jump on a bus to Hosshinmon-oji (発心門王子). The plan: walk down to Hongu (本宮). Most people just walk straight from here, but, presumably, the views as you descend from Hosshinmon-oji are nicer than starting in Chikatsuyu, so we will make that bet. We’ll hop on a bus to get to the trail. Ultimately, the destination is the same.

Slow stroll through Chikatsuyu

***

“What’s going on here?” I wonder, confused as I get on the bus. There’s like what appears to be two hundred people inside. It feels chaotic and messy, and everyone’s staring at us while we orient ourselves. I sigh. “I can’t believe we’re standing for a whole hour with these heavy bags!”.

As I look around to figure out where to stay or where to stack the backpack, humbly peeking over backrests in search of spots, I notice people are sitting on their luggage in the aisle. “Weird”, I frown one eyebrow. I’ve never seen that before. It looks totally unsafe, but who am I to judge?!

A woman points at me and to the aisle, as if saying, “You, stay there!” I get even more confused. But, as I scan the corridor, I don’t see any suitcase or luggage wheel. Wait a second! This bus has a fifth seat that folds from beside another seat, fitting five people per row! I nod and, while saying a few Arigato’s, rush to sit down.

Japan really is the country of the future.

As the bus stops and collects Americans and Europeans, they, one by one, interject and laugh, "hey, look, there's another seat in the middle!"

We walk on asphalt for 10 minutes before getting on to serious business. The trail is stunning, with the modern roads meeting the old. Asphalt and hamlets again, a symbiosis of community and nature.

***

The trail is breathtaking, and some spots seem to whisper in my ear, “Please, stop and admire me”. I oblige, of course.

We slow down, gazing at the quaint hamlets, letting our eyes absorb the light like a sensor during a long exposure, etching memories onto a film of our minds. We want to remember this moment later, as vividly as possible.

Suddenly we’re out of the woods again, into a small village in the mountains.

And back again into the woods.

The middle of today’s trail gets challenging, like a game of Tetris, except it’s your feet trying to fit the right spots. The staircases aren’t built for regular steps. Their geometry is all over the place. I feel a sense of alertness and mild discomfort while walking. “Preserve the ankles, preserve the ankles”, I repeat as mantra. It’s quite easy to get hurt if you’re not careful.

There are passages where my whole mental energy is focusing on where my feet are landing. Just that and nothing else for several minutes. And then, at certain points, I pause and admire the beauty around me.

I have seen ancient tree roots serving as a long stair up and down. I have seen stairs made of rocks naturally. I have seen stairs with uneven steps. I have seen them all mixed, roots, rocks, sand.

The most impressive, however, are the ones that were crafted by the feet of the thousands and thousands of people who have, a step at a time, helped shape these trails.

In between the woods, we spot what appears to be the outskirts of Hongu. Our expectation to see the tall torii gate grows exponentially. When planning, this portal was an important milestone of the journey. It represents the reinvention of oneself, a transition, an end and a new beginning. We are almost there.

We arrive at the Hongu Taisha area, respectfully appreciating the view of the shrine, and taking some time to admire banners, the architecture, the gold and silver. We continue down the stairs leading to Hongu.

Crossing the village into the fields, we arrive at a special place we’ve been anticipating for months: the imposing Oyunohara (大斎原) torii, a tall 111 ft gate (33.9 meters) that represents craftsmanship and transcendence. This is it, the gate I’ve wanted to visit for so long, finally in front of my eyes.

Portals

I feel like a tiny ant standing in front of this torii gate due both to its height and personal significance.

Have you ever noticed how portals are everywhere in our culture? In Alice in Wonderland, the main character needs to go through a tiny portal to get to the other side of her reality. In Narnia, a hidden portal inside a wardrobe leads the characters to another world. The Matrix, Stargate, Interstellar’s wormholes are other examples.

Some portals are conceptual, like event checkpoints. When Einstein discovered Relativity, the human race went through a portal after which life wouldn’t ever be the same. Penicillin, vaccines, combustion engines, the printing press. They’re all around us.

However, portals are hard to be found. When you find them, you must make an intentional decision to go through because it takes effort. Once you do, your life changes forever, and you can’t fathom returning through it to your old reality. It’d be like death. Often times, you will come back to try and tell others where the portal is, but they downplay it, or laugh at you. You might try to tell them how it is like beyond the portal, the colors, the smell, the magnificence, but they won’t understand because they haven’t seen it for themselves.

In 2011, I crossed one such portal. Living in a 5,000 inhabitants rural village in south of Brazil and with a 250Kbps bare internet connection, somehow I managed to get a tech job in the US. On the other side of this portal, my life had changed forever. I learned new ways of thinking, how to be productive, successful examples that challenged my education thus far, and how value is generated. For years, however, people thought I was a lunatic. You know, small town chatter. I tried to help others come through the portal, but they either couldn’t find it, weren’t willing to make the hard decision, or found it impossible.

Shinto torii gates captivate me because they represent a transition from mundane to a new reality, like the hidden portals around us. They are a celebration of the many passages distributed throughout space and time, yet hard to be found. They reward those who make the required decision to go through them, with a willingness to leave the past behind.

Being here has a special meaning this evening. This torii represents our quest for hidden portals. Quite possibly, having done this pilgrimage could mean I crossed another portal and my life will never be the same. Maybe I will finish this journey a different man than how I started it.

Too early to say, and it’s getting late. It’s time to go get some rest. Tonight we sleep in an Airbnb in Hongu.

Day 3: resting in Yunomine

Steam, river stones, and slowness

We wake up to a chaotic morning, rushed and on empty stomachs. Google Maps had told us cafés and restaurants would be open today, but guess what, they were closed. Walking through streets on an empty stomach to find closed doors isn’t fun. Fortunately, we stumble upon a small grocery store and throw together the quickest breakfast before check-out.

Today we’ll head over to Yunomine (湯の峰), a small hot springs village. Tsuboyu (つぼ湯) is renowned as Japan’s oldest onsen and a UNESCO World Heritage site. If things go according to plan, we’ll chill, soak in hot water, and sit on a bench until our butts go numb. We’ll watch the flights of birds, kids playing and trees dancing.

***

We are the only passengers in the mini-bus. We are dropped 40 minutes away from Yunomine.

We walk uphill on a hot and bright asphalt. The lack of shades on the road makes us stop a few times to cool down our body. It’s 90F (32C). Who said this was going to be a rest day?

Half an hour, a relatively short walk, but my back already hurts nonetheless. This background discomfort is a recurring theme since the beginning of the journey. Two weeks ago in San Jose, back in the US, I turned to AI to help me diagnose the symptom. “Alex, what you’re describing (tired, achy mid-back muscles next to the spine, not sharp or injury pain) sounds like muscular fatigue from postural stabilizers, the muscles that keep your torso upright”. The knowledge that it’s likely fatigue has given me confidence to continue the walk everyday, with the proper, systematic resting cadence. Still, it seems to get a little bit worse every single day.

We arrive at the small village and find empty streets. The central canal releases steam.

Not a single soul, a pleasant surprise.

We drop our backpacks at a random spot and wander around to get to know the place. This is Japan, no one’s going to steal your stuff. We roam around a nice, cute little village, then head to buy tickets to Tsuboyu, the famous, UNESCO onsen.

Honestly, I’m mildly reluctant to dip into almost-boiling water, given how hot the sun is. The Tsuboyu hut lets steam escape through its wall gaps, like a toaster made of wood. It’s a mild sauna inside and the water is freaking hot. After several failed attempts to dive my toes, we finally soak, like two potatoes in the pan.

Before leaving the steaming hut, I finish with cold water, which leaves a lasting freshness. My skin stays cold for a good hour or two afterwards during lunch. A small, wet towel wrapped strategically around my neck makes me feel like a relaxing capybara.

The hut where Tsuboyu is located.

Our lunch involves doing the traditional Onsen Tamago, where you hard boil eggs by dipping them in an open hot spring for 11 minutes.

After lunch, we find ourselves a wooden bench. As my legs touch the wood and I sit, it feels like Rest Day has finally began.

Your browser does not support the audio element.

The tranquility invites us to play a little game to enhance our perception: Five things we see, four things we hear, three things we feel, two things we smell, one taste.

Treetops, children, traditional houses, flags, flowers. A breeze, a conversation in Chinese, children, birds chirping. Peace, privilege, sore muscles. Hot spring scent and flowers. Eggs.

We are hyper-focused on the present. A while ago I was preoccupied about making good use of the time, now my mind has calmed down. I’m just enjoying the wind blowing my skin.

Ice cream wouldn’t be a bad idea.

***

We hop on a bus towards Kawayu (川湯), a tiny village where hot springs flow into the river, and arrive during sunset. We borrow traditional robes from our guesthouse and wander, shy, towards the natural spa. You can use a shovel to dig your own bath spot in the river, but we decide to use an existing spot made of stones. Under a sky full of stars, we soak, mixing and contrasting hot and cold water. A perfect ending to our night before dinner and bed.

Day 4: Kogumotori-goe to Koguchi

Long ridges and thoughts

We woke up to a gut punch before coffee. Both my wife’s knees and mine are hurting, and my back is doing a serious complaining, while today’s trail is the toughest.

The 13km Kogumotori-goe (小雲取越) trail’s first third scores 4 out of 5 in difficulty. It’s a gradual 1,542 feet climb (470 meters) to Hyakken-gura, harder than Day One, which was already quite taxing. More pressing is the fact that Koguchi (小口) has no lodging available today, so we must arrive before 5pm to catch the last bus to Shingu (新宮). The trail estimates say 6-8 hours.

At 7:45am, we’ve spent an hour working the problem. The heavy backpacks aren’t helping our knees or backs, so we conclude it’s irresponsible to walk with this much pain. The options are doing a boat tour today (I didn’t come here to sit down); finding another trail (frustrating after months of planning); my wife taking a bus to Shingu while I walk (I’d feel bad for her); walking a third of the trail and returning (sounds off-putting but better than nothing).

Shipping weight

“If only we weren’t carrying our heavy backpacks”, a lightbulb pops over ours heads. “What if we could leave our bags here and return”? That would be an inconvenient 16km return after a tired day of walking. “What if we could ship more weight to Kyoto”? That’s not impossible. We would need a container and right now we only have two backpacks. I ask ChatGPT for ideas, “why don’t you check with the guesthouse’s owner if he have a cardboard box you can use?”, the AI asks. That’s a good idea. I run downstairs to check with him, and after a couple minutes, he comes back with a finds one in the trash, the perfect size. I assemble it in a square

We pack into the box everything we can find in our bags. The camera stabilizer stick, a camera, moisturizers, eyedrops. The lightweight laptop I’m carrying for writing. We tape it carefully, and there it goes to Kyoto.

We feel a little bit more optimistic, as if a ton had been lifted from our backs and our minds. The frustration is replaced with hope, we decide to keep the expectations low and set a simpler goal: walk 5 long kilometers to Hyakken-gura, the highest point, and re-evaluate. The peak is a third of the way, so it’s presumably easy to get back if have to.

Once there, we will figure what to do next.

Kohei-san, the host, after solving our shipping and preparing a delicious breakfast, kindly offers to give us a ride to the trailhead with a smile from ear to ear.

Back on trail

Twenty minutes into the walk, adrenaline triumphs over any logical reasoning and makes us both say, “Fuck it, let’s just keep going until the end of the trail”. Ah, the overthinking! At least it served us in shipped weight, but did we need the drama? We laugh. “It would be too frustrating to return once we’re on the move”.

It’s 9:17am. We see humans beings on the trail, everybody faster than us. Our goal is reaching the peak of the trail in 2-3 hours, hoping we’re left with plenty of time to continue on a slower pace.

I keep asking myself, “Are we behind”? I look at the offline map and I still have no idea where we are. We’re walking fast and steady, like runners in a marathon chasing a gold medal. We feel like arriving at any moment. It feels also like the hardest trail so far. By a mile, figuratively and literally.

Five kilometers on a straight line would take me roughly an hour to walk, so the whole 6-8 hours the Tanabe Prefecture stipulates never made sense to me.

And if we get there ahead of time, say, before 11:45am, then we’re gonna make a decision about going all the way. In theory, a third done in 2:45 hours means a total trail roughly 8 hours. The last two thirds would be downhill, which is presumably easier, but also terrible for knees like ours.

If we got injured, could you imagine the inconvenience it would be? Waiting for someone to bring help? Nah, that’s virtually impossible. A worst-case scenario looks like a slow zombie walking on a trail back to civilization. The scary is getting dark, no lights, nowhere to sleep, and then maybe I have my first ever homeless simulation. I mean, it wouldn’t be the end of the world, but definitely not something I want to experience today.

A new friend

Our conversation breaks off when we see someone walking backwards, moving slowly. I signal my wife to stay behind and go check out.

A person on the trail.

“Hello? What’s up?” The woman looks at me. “Uh… snake. A snake up there”, she says, gesturing up the trail. “Let me go take a look”, I say, and move forward.

I scan the endless grass and leaf litter along the trail, but see nothing. Then, as I approach, the reptile glides down from the embankment above us onto the path, as if it wants to join our walk. As I close the distance, the snake angles across the ridgeline and disappears downhill. “Clear!”, I announce.

“Would you like us to walk in front of you, just in case”, I ask. “Yeah, sure”. We restart the march and I present myself and my wife. “I’m Fey”. My wife lags behind with her while I lead the group.

Over the next hour, a cultural exchange flows non-stop. We learn she’s a Chinese kindergarten teacher on vacation, skipping the Chinese hiking trails this time to walk the Japanese ones. Yesterday, she walked up until late at night. “It’s common in China for people to hike in the middle of the night”, she says. “Aren’t you scared of the dark or animals?”, we ask. “Yes, but we do it anyway. I use my cellphone lights”.

Brave woman.

The peak

Overcoming the struggle, we arrive at our checkpoint, the Hyakken-gura. I wonder if the clock is broken, it’s 10:20am and nothing makes sense. “How did we arrive in one and a half hours?” We rushed, sure, but the terrain was the hardest we’ve experienced and our most optimistic plan expected at least two to three hours. Yet, we managed to get to our goal in half the time!

None of that matters now because the mesmerizing Kumano mountains fill my eyes. The green horizon casts a hypnotic spell, putting everything secondary.

The Kii mountains in all their glory.

What a view.

We decide to continue on our way to Koguchi. We take a few more pictures, turn left towards the trail and… restart the march, as if any other option is inconceivable. At some point an hour ago we thought, “Yeah, I just wouldn’t feel good returning”, and so we just kept going. After all said and done, the decision comes in seconds, based on gut and feeling.

And that’s fine.

Koguchi

The final descent is brutal on our knees, a continuous and relentless 2,260 ft (690 meters) drop. The steady rhythm of 3,750 steps pounds our joints like a pickaxe. The endless staircase forces frequent pauses, alternating pain with brief relief over an elevation loss equivalent to 225 flights of stairs.

My right knee shakes back and forth when I stand upright, like a column in an earthquake. We see a gradual increase in brightness among the trees.

The end of the trail is near.

An endless descend

Exhausted, we reach the end of the trail at 12:10pm, thankful for having arrived. We continue to Koguchi to find food.

“I wonder whether we would have the energy to do the next trail right after, the Ogumotori-goe (大雲取越)?”, the fleeting thought crosses my mind. In ancient times, it was known as Dogiri-zaka (胴切坂), or “body-breaking slope”. It’s nothing less than a sudden 2,625 feet ascent (800 meters) in the first 5 kilometers.

Do I have the energy to do the second trail? Probably yes. Can my knees sustain a body-breaking slope? Certainly not. Everything hurts. I am destroyed, I’m tired, but I’m happy.

We walk by half-dozen houses next to the trail's end

A peaceful fisherman

Koguchi

We arrive at a camping area that has a single food truck, called Bar Free Soul. The owner serves us gyoza (餃子), and asks us to pin our country on a large map behind the counter. I raise an eyebrow the moment I see pins everywhere, except Brazil, before adding my pin. We’ll chill here until the next bus to Shingu stops by at 4:30pm. It’s a long wait.

Fey, our new friend, rests for an hour before finally deciding to start the next trail toward Nachi, the Ogumotori-goe. We clap at this brave woman as she departs with her green backpack.

When it’s time to leave, we hop on a bus to Shingu. The vehicle is packed and we travel standing up for a good hour. After arriving, I’ll need to figure out how to dispose of my unused bear spray.

The bus from *Koguchi* is packed with walkers speaking languages from all countries

Bear spray disposal

The disposal of a bear spray is one big challenge when it’s your first time disposing of it, you are in a foreign land, and you want to do just the right thing. Think of a pepper spray, but on steroids. It shoots nearly 60ft (about 20 meters). It’s an explosive red goo that you clip to your belt. You can’t toss it in a regular trash bin, and you cannot fly back home with it either.

According to ChatGPT, Claude, Grok and Reddit (I quadruple-checked), the general guidance is to take it to a police station (kōban, 交番) and ask for help. Not exactly easy when you don’t speak the language, and you’d rather not look like a lunatic with a canister in your bag.

Arriving in Shingu, I walk to the police station. Through the large glass door, I see no one inside. “Out on patrol. Return later”, the sign says. So I sit on a park bench nearby and wait an hour.

Then, two policemen appear down the street. I pack my things, ready the bear spray its bag and head toward the station. Just as I’m about the reach the door, the two officers sprint past me, jump into their car, flip on the siren, and race off to deal with something clearly more urgent than a confused foreigner holding a can of bear spray.

In Japan, manufacturers recommend discharging contents either outdoors, or underwater in a bucket if that’s not possible. Not really feasible from a hotel room. A problem for another day¹.

Day 5: Shingu to Nachisan

The final ascent, and a timeless fall

Our schedule is tight today because we’re sleeping in Kyoto tonight. We need to catch 7:00am bus toward Kii-Katsuura (紀伊勝浦) and Nachisan (那智山). That gives us 8:51am to 10:32am to explore the temple and falls before five or six hours of trains to Kyoto. We cannot miss that bus.

But we wake up late. Empty stomachs, bags on our backs, and only 10 minutes to walk a 20-minute distance, we kick start our rushed walk towards the nearest bus stop north of us, which is impossible. Giving up, however, isn’t an option. I pull up the map and spot a chance: the bus line curves through the city, so if we cut west, threading narrow streets like a needle, we might intercept it fourth stop. We hope the bus is slow, crowded even.

We walk the fastest 15 minutes of our lives and make it. The bus is coming on the horizon and the day is saved.

We arrive at Nachi station on an empty stomach, and depart to Nachisan. We head straight to Nachi-no-Taki-mae because we have no time to climb the Daimon-zaka (大門坂) stairs today.

Yakult to wrap the stomach, followed by cold, canned black coffee to tune our ambition

Nothing to see here, just a tsunami height warning

I look at the clock when the bus arrives. It’s 8:57am. As we step out, we reorient ourselves, among a crowd of visitors. Looking right, there’s a torii gate leading to the Nachi Falls. Turning my head left, a staircase that leads to the Nachi shrine.

Nachi-no-Taki-mae is a bend in the road that feels compressed by traffic and guardrails. A small parking lot sits in the corner, a clutch of souvenir shops lines the curb, and a signed path leads towards the falls. Buses sigh, people reshuffle bags, and the crowd moves on. It works as a waystation more than a place to linger, a stop where you wait to get somewhere better. A liminal space.

As we stroll towards the falls, can you guess who we spotted, out of the blue? Yes, Fey. We hug and rush to ask about her adventure yesterday, when she kept going after we stopped in Koguchi. “It was hard! I kept walking until darkness, arriving around 10pm”, she told us. Without a lodging reservation, she roamed around and was lucky to find an available room in a random guesthouse. “Scary”, she says with a nervous laugh about walking at night. “I found a mother and her son in the trail, and we finished the route as a group together with our phone light. Then I knocked a few doors and found a spare room to stay.”

Brave woman.

Fey

The clock is ticking and we have to run. We say our goodbyes and rush to the stairs up to the temple. The first step feels like the hundredth and my thighs burn on the push. I reach for a handrail, but there’s none. However, when I remember it’s not an endless staircase, my shoulders loosen and I let out a breath. Today is short, we ought to make the most of it.

The stairs are made of rounded stones that seem to stretch beyond the horizon. It curves left and right. We stop to catch our breath and see the ocean in the distance fading into the cloudy sky, cradled by green hills. The village keeps getting smaller.

A few flights later, we lift our heads to the sky and glimpse vermilion in between the green leaves. Still faint, it imposes itself from above. Our destination draws near.

A staircase is a small cost to pay to get to the famous Nachi shrine

“We’re here, pinch me please”, I ask my partner. We have arrived. The shrine’s red, once only pixels on a screen, now fills my eyes. The water that ran behind this place a thousand years ago still runs, stitching past to present.

Nachi Shrine & Falls (青岸渡寺)

I finally let go of a breath I didn’t know I’d been holding for years. My shoulders are lighter, free from the weight from everyday life. My chest feels full while I contemplate the satisfaction of achieving something bigger than myself.

The man who’s stepping on the train back to Kyoto is not the same man who stepped on the trails five days ago. I found the reset I had been looking for.

After walking the Kumano Kodo, I learned that the walk was the destination, and each step was an arrival. This journey has come to an end, but the pilgrimage continues. The trail has become a metaphor for life.

I crossed a portal, and now everything looks different.

Tomorrow

New paths

After finishing the Kumano in the 12th century, the poet Saigyō Hōshi (西行法師) wrote the poem,

吉野山
こぞのしをりの
道かへて
まだ見ぬかたの
花をたづねん

Mount Yoshino
I’ll leave last year’s marked path,
take a different way,
and search for blossoms
in places I’ve not yet seen.

The poet’s vow to change the road resonates with me. It’s an invitation to honor what was just walked, but to pivot and keep seeking “blossoms”, insights, and wonders on new paths. It’s an invitation to carry the pilgrimage mindset onward, as a new person.

That’s what I’ll do.

On the journey from Nachisan to Kyoto, I made a brief stop in Tanabe and returned the bear spray to Stock Outdoors, where I'd purchased it. The owner graciously gave us a discount on the return.

Planning a walk in Japan

2025-09-29T00:00:00+00:00

In six months or so, I’ll walk the Kumano Kodo in Japan. The idea of doing a total reset had been popping into my mind for a while, a certain attraction to disconnecting from habits and the world to reconnect with myself. A quiet, five-day journey through mountain passes and primitive, lush forests looks like the perfect setting for that.

The Kumano Kodo trails are special. For thousands of years, they led pilgrims to majestic temples in Hongu, Shingu and Nachi, connecting all walkers of life in search of meaning, salvation, or just adventure. The absense of Switzerland-like turquoise lakes and Italian-looking alps means that the region doesn’t impose itself as the movie’s main character, but as a pleasant companion for the journey.

My humble walk from guesthouse to guesthouse is meant to be distraction-free. No social media, podcasts, music, just the here and the now. No autopilot, only being present.

“All truly great thoughts are conceived while walking.” - Nietzsche

Concepts

the walk is the destination, the temples are just rewards

A good walk

In my book, a good walk will be boring, memorable, and pleasant. Boredom benefits our brains by opening space for inward reflection and creativity. External impulses, on the other hand, steals our focus. In a world of infinite stimulation, boredom heals. Thoughts get shaken like a tree, and the bad apples fall to the ground.

Nearing fourty, you bet it has to be goddamm memorable. Trails are everywhere, but they don’t come with flights to the other side of the planet, trains sliding by at 200-miles-per-hour, and milenial history. “I walked for days in Japan” carries its own weight to anyone who hears it, regardless of their origins. It absolutely does for me. Plus, the Nachisan temple and waterfall are a spectacularly great finale.

Making it pleasant means primary memories will be about reconnection, reflections, mindfulness. The adventure needs challenges to be fun and rewarding. However, a monumental struggle through mood, torrential rain or scorching sun would tip the scale in the opposite direction. I don’t want to remember it being 75% good, the rest being burden and annoying problems. I mean, I don’t expect it will be perfect, but I’ll do what I can to keep it a great experience.

Five-to-six days feels like the absolute sweet spot. A one-day walk doesn’t carve out enough memories. It doesn’t get boring enough. A 10-day walk, on the other hand, advances the boredom and pain. Two days, three, none look like it’d leave a deep enough mark. Five days, though, that’s the perfect shape for this walk’s objectives.

The shape of the walk

To be in the present, no modern distractions are allowed. No mobile phone, no social media, no podcasts or music transporting us elsewhere. Taking pictures is a must (memorable, remember?), but even that could be distracting, so I’ll be intentional and keep the shutter movements limited to certain time windows.

One rule is that no more than 15 miles (~20 km) will be walked per day. I need to keep in mind that I’m an amateur that will be carrying a 15-20 pounds backpack. Guesthouses will be waiting before dawn everyday. I won’t feel bad if I have to take a bus to respect my limits.

A rest day will wait for me on Day 3. That day will serve for reflection about the previous day, while my sore legs recover for the final push. A great candidate is Yunomine, the oldest onsen in the world. That depends on what trail will be chosen.

Overall, we must reach our destination everyday by 4pm. Guesthouses prepare baths by 3:30-4pm, and dinner is served at 6pm. Arriving later will make leave hosts quite annoyed and unhappy.

The Kumano Kodo is a UNESCO heritage pilgrimage trail, and you can collect stamps along the way. Honestly? I don’t care as much about that. It’s a nice-to-have, sure, but I won’t care if I don’t get it, especially if it’s for a better trail.

What would be the ideal trail?

❈ 117 days to the walk

The decision to walk the Kumano Kodo was made a long ago, but the indecision lingers about which route. There are many, all coming from different regions but leading to the same temples.

The ones that stand out are the Iseji, a 130 mile (~170km) journey from the city of Ise, threading through mountains and beaches, through fishermen villages by the Pacific coast; the Nakahechi, a more traditional hike starting from Tanabe through gorgeous forests and mountains passes; the Kohechi, a tougher version of the Nakahechi, starting or ending Koyasan to the north; or the Nakasendo, a 350 miles (~500 km) traditional road people used to travel between Tokyo and Kyoto (not Kumano Kodo, though).

I spent a lot of time reading about these trails, you have no idea. The Nakasendo looks absolutely gorgeous, it still preserves the architecture and style from the Sengoku period, when Samurai’s would traverse those roads towards the capital, but my heart is inclined to Iseji and Nakahechi. The Kohechi looks ok, but I sense it’ll be too painful for an amateur like me.

Iseji is longer and its beaches add variety to the walk. Walkers mention an awe, as you walk down from the mountains towards the ocean. Nakahechi is a traditional hiking trail, with more severe elevation gains, deep into the forest. It is beautiful, don’t get me wrong, but it’s not as beautiful, although its utmost historic importance.

The more I research, the more crystalline is the fact that the walk is the destination. The temples a gorgeous, but they aren’t as special as the process. The true reward is living in the moment, slowing down, entertaining primitive thoughts as the lush forest opens up with every step.

Planning takes a hit

Personal and business matters force me to spend a month in the United States immediately before the walk. I’m suddenly forced to pause the Kumano Kodo’s research and plan another juggernaut of a trip. There are simply too many logistic details to figure out.

Where can I exercise? Where can I practice stair climbing? For each Airbnb option, are there grocery stores at walking distance? Should I purchase hiking gear in the US, and if yes, where?

Spoiler alert: the trip gets considerably more challenging with US in the equation.

A new partner

This trip was supposed to be solo because my wife had an unavoidable work schedule. I had no choice, I had take vacations this year or I’d lose it.

Winds changed direction and my wife was able to free up her scheduled, so she’s joining me in the walk. The overall purpose and rules still apply, but a rather gray-ish journey suddenly became colorful.

The scale tips towards Iseji. My wife has a preference for the coastal walk. The images are incredible.

The ground shakes

❈ 59 days before the walk.

So, Iseji or Nakahechi? I’ve spent way more time than I’d like to admit choosing between the two trails. So-much-research. One such aspect is bears. My YouTube feed algorithm suggests now only topics like, “How you’d not survive a bear attack”, and “The ten worst bear attacks in history”. I regret having searched about that at any point.

A whole article could be written about the Japanese black bears. They are more pervasive in the north of Japan, roaming villages, foraging trash, but nonetheless present along the Kumano Kodo. Encounters are extremely rare, but my instinct compels me to spend weeks reading about the topic, triangulating sightings from local prefecture maps to calculate odds of being the lucky one to hug a bear (or be hugged by one). By my estimations, it’s 4 times more likely to be bitten by a dog than encounter a bear. The bad news is that I’ve already been bitten by one.

Then, something unexpected happens. A magnitude 8.8 earthquake off Russia’s Kamchatka Peninsula triggers tsunami warnings across Japan and the US, and the decision about Iseji sort of self-resolves. It’s a road on the coast!

I mean, tsunamis are rare and even if they occur, sirens would howl hours before any catastrophy. We’d just walk to high ground. However, would I want to walk while my brain is in constant alert about a potential wave washing us off? I don’t think so, despite how gorgeous Iseji is. More or less at the same time, I learned that bear sightings are way more common along the Iseji road too (probably because it’s a longer road, I suspect), in relation to the Nakahechi.

In any case, it feels way, way less stressful to walk the Nakahechi and leave the Iseji for another time.

The Nakahechi trail

The objective is reaching three checkpoints: Hongu Taisha, a humongously tall torii gate; Shingu taisha temple; and finalizing in Nachisan, a majestic red temple built in the 7th century, with Japan’s tallest waterfall as background.

To hit those goals, I’ve spent more time researching trails than I’d like to admit. In which order should we arrive at those temples? How do these trails connect? How to limit a day’s total distance walked and still make to destinations? Where to grab food? What are the potential guesthouses? And then checking a guesthouse’s availability you discover it’s alreayd fully booked, forcing you to get back to square one.

Overall, we know where we want to start and end. Takijiri-oji to Nachisan. We could start in Takahara which is close, but we’d miss the traditional stone stairs. Nachisan is the great finale we are looking for, with one of the most beautiful temples I’ve seen, with the highest waterfall in Japan as background.

After much deliberation, the overall itinerary in my mind looks a bit like this:

Day 1: take a bus to Takijiri-oji, and from there walk to Takahara (~3.7 km, 1.5–2.5 h; difficulty 2.5 / 5), then to Gyuba-dōji-guchi (~8 km, ~3 h; difficulty 3 / 5), and arrive in Chikatsuyu to sleep (~1.3 km, 30 min; score 1).

Day 2, arriving in Hongu: we start the day in a bus to Hosshinmon-oji, and walk to Hongu (~7.5 km, 2–3 h), where we will see the tall gate (Taisha).

“Why take a bus?”, I can hear you asking. Well, the views as you walk down the Hosshinmon-oji are way more beautiful, and the distance is more or less the same. There’s also a nice spot to take pictures of the Hongu Taisha as you descend the mountains.

Day 3, rest day: I’m uncertain where to go, but Yunomine is the best candidate. It’s the oldest onsen in the world. People travel the world to bath in these waters, and it’s only 3-4km from Hongu.

Day 4, hardest walk to Shingu: we walk the Kogumotori-goe, the longest and hardest day, arriving in Koguchi. Difficulty score 4 out of 5.

(A note from the future: I learned later that Koguchi doesn’t have logding anymore, so the plan is to get there before 5pm, which is the last bus to Shingu. Somewhat… dangerous?)

Day 5, Nachisan finale: we take a bus from Shingu early morning and climb the famous Daimon-zaka stone stairs to Nachi Taisha and falls. We take a train out back to civilization.

T-44 days to hike

It feels like an eternity, the wait until we put our foot on the trail. Despite the ample time, some of these villages have only a handful of places to sleep, and they book fast.

Koguchi seem to have one available place to stay (although if you walk into further trails, there are more options, but after a long day, that’s not going to be great). You’ll see that two days later, I learn that Koguchi doesn’t have any lodging available anymore.

***

Physical conditioning is another issue. I’m far from the ideal shape. Where I live, surfaces are flat everywhere. The only option is gym training and long walks.

During walking practice, I realize my back isn’t in great shape. I suspect it’s due to posture. ChatGPT tells me its suspicion is weak minor stabilizing muscles. I consciously hold my core stiff as I walk and the pain subsides. One pain points relieves, yet another starts: my left heel is starting to ache, like a tiny knife is pushing up. The back pain returns, now closer to my hips.

(Comment by a traveler from the future: these specific pain points remained a challenge until the very end of the walk.)

After 20 minutes, my thoughts get gradually more constrained until they almost disappear. It’s like a kind of meditation session. I’m more focused on whatever is important. My thoughts aren’t all over the place anymore.

After 9 km, my back pain score is 5 out of 10. It’s not terrible, but just enough for me to remember every second that my back exists. I also didn’t have lunch and now it’s 3:14 PM so I had to have a banana. Coincidentally or not I feel like this was the most delicious banana I ever had.

I finish the training after 10 km. Two hours, an annoying back pain, and a knife in my shoe.

Logding

I get a scary message by Craig Mod. I completely underestimated the scarcity of places to stay along the Nakahechi.

Alex, if you haven’t booked lodging yet, I suspect you may just have to do with whatever’s available. For Nakahechi, a lot of folks book 6-months out at least. Please report back how finding lodging goes.

Using the Japanese reservation website feels like time travelling to the 1991. The system is terrible. The Tanabe prefecture website, which intermediates reservations with the various village inns, does not work before 9am Japan time.

The KUMANO TRAVEL Community Reservation Site is only open to receive new requests during set operational times: Daily 9:00 to 17:00 (Japan Standard Time).

Yeah, they took the physical world and replicated online. Well, I’m thankful that at least I wasn’t required to fax them!

For the next 2 days, I aggressively research and book guesthouses / lodging. What a relief. I feel pretty lucky to have found options: a series of simple

Day zero at Michelin guide guesthouse: a proud discovery we made was this Airbnb in the mountains near Takijiri by an italian chef. Dal creates has own goats to make his own cheese, and sources his vegetables from his own garden. It feels like the perfect to sleep before the walk.

Getting there, however, is a huge challenge, and the whole operation feels like we compressed a thousand tasks into a few hours. Once landing in Tokyo after a sleepless 12h flight, we have 24 hours to travel roughly [todo - numbers] 430 miles (690 km), buy hiking gear, organize our bags, store our luggage somewhere, and figure out how to navigate the transporation system.

T-40 days to walk: a message from the Kawayu’s guesthouse (Day 3) arrives detailing what they serve and don’t. On that Wedsnesday we stay there, dinners won’t be served. It’s also a village without grocery stores or restaurants.

Elevation Reckoning

The day I realized a trail has +1,000m / 3,600 ft of climb. I completely underestimated the walk. Just 41 to prepare.

I sip a cup of tea on a Wednesday at home, 9pm. Watching random thoughts run free in my mind, some walk-related, some are work-related, I recall how untrustworthy Google Maps is for plotting trails, and wonder how Apple Maps is doing on that front. A recent announcement promised hiking trails with higher precision, so I check it out.

Apple Maps displays 3,608ft elevation

“What?”, I gasp. “A kilometer?”, I incredulously stare at my screen for a few seconds while my head spins around. “That can’t be right, riiiight!? This is Apple’s new software, maybe it’s a bug.

I suddenly feel the dumbest person for not being aware of that kind of very-critical-detail. I mean, I’m flying to the other side the planet, watched dozens of videos, checked routes, bus lines and schedules over and over, how one of the most important aspects went unnoticed?

I’m already at arms-length into this hike, lodging is booked, I can’t give up. I won’t give up. So I turn to Claude to get more details.

Claude: Looking at the Kumano Kodo trail data, from Takijiri to Chikatsuyu involves approximately 3,313 ft of elevation gain over the ~14km distance.

You’re looking at about 337 flights worth of elevation gai…

“337 flights of stairs?”, I gasp again. That’s… (counting on my fingers) climbing my apartment building 24 FREACKING TIMES. I’m faced by a monster bigger than me, a hill too tall to be conquered by someone who hasn’t ever hiked. I’m also scared anticipating how my partner will hear this disturbing piece of news.

I can’t give up, but I could definitely change the plans. I pursue that idea for… 2 seconds. I let that concept flash in my mind, only to realize retreating would leave me feeling unhappy and uncapable of doing what many thousands have already done. I mean, I could start off in Takahara, but it’d be flat and easy surface from there, would I feel proud of myself? This is not an Everest hike (that one is risky by definition), it’s the Kumano Kodo; it doesn’t look that big of a deal. So what’s the real problem? Is it really impossible to do this hike? Or am I judging the situation prematurely? Maybe I just need more information before I can make a decision.

Research mode

“Ok, so, I need more guidance”, I tell Claude. “I have roughly 30 days, I can walk on a flat surface for 15-20km. I don’t seem to have enough time build up muscle to climb 300+ flights in a single session, but during the hike, I will not need to climb 300 in a single session anyway; it’s distributed over 13km.”

There’s no size-fits-all and Claude doesn’t know me, so I need a range of numbers to understand where I am. I continue, “What are the no-go, minimum, and ideal number of stairs that I need to be able to climb in a single session to train for this hike, considering that during the hike I will stop a few times for resting, and also for lunch? Let’s be realistic.”

Claude: Given your 30-day timeline and current fitness (already walking 15-20km / 9-12 miles flat), here are realistic target for single sessions:

No-go: Less than 60 flights continuously without major distress

Minimum: 100-120 flights total (can break into sets of 20-30 with 2-3 min breaks)

Ideal: 150-180+ flights total in a session

You’re right - you won’t need 300+ continuous flights. The elevation is distributed over hours with natural breaks for views, photos, snacks. If you can do 150 flights in sets during training, you’ll manage the hike.

I lack reference points, but 150 is a bit more reassuring than 300+. That looked impossible. This? Ugh, it’s still 150 floors. I don’t remember ever walking nowhere close to half that many. I remember walking up 17 floors to help out a friend during a power outage. I got up there and was sweating, but I remember feeling like I could do more in a life-or-death situation. Probably not 133 more. Not probably, certainly.

AI’s can be exponentially more helpful when given details about time, place and your state of mind, so I share my schedule for maximum customization. I replace Claude with ChatGPT because it’s better at cranking numbers. “Week 1, I’m in an apartment building with 14 flights of stairs; on week 2, I’m at a hotel in San Francisco (it has stairs); weeks 3-4, Airbnb without stairs in San Jose’s Santana Row area, no idea about gyms; week 5, I’m attending a company offsite in Vail with access to gym; week 6, hike starts”.

I get back a plan. The looks is surprisingly detailed, tailored to my precise needs.

If you can string 120+ floors once a week (plus flat mileage) by mid-September, you’re realistically ready. Hitting 150+ gives peace of mind.

Week 1 — 14-floor bldg: do 168 floors (total 6 loops, up only). 84 floors in 2 sessions. Walk down via elevator to save knees. Add 5 kg day-pack on 2nd session.

Week 2 — SF hotel: shoot for 100-120 total in 1 session. Target ≥ 120 floors. Add 1 shorter 60-floor lunch climb.

Weeks 3-4 — Santana Row, no stairs: if no gym is available, find a parking-garage (Valley Fair garage has 6-7 floors). Target 120 floors week 3, 150 week 4.

Week 5 — Vail, hotel gym + altitude: peak session: 160-180 floors continuous. Altitude makes lungs work, so keep heart rate below 80% max, and hydrate.

Week 6 — on trail: You’re tapering—just easy walks. Focus on sleep & nutrition.

I stand up and ask myself, “what am I doing”?

***

My partner needs to know what’s going on. “Hey”, I greet, “got a minute? I have good and bad news, which one do you wanna hear first?”, I ask rhetorically, proceeding almost immediatelly: “The bad news is that on Day 1, we’ll need to climb 1 kilometer”. I pause, and she frowns with a face of calculation. “That’s equivalent to 330 floors. Our building, times 24”. She gives me a blank stare for a second or two, then begins laughing uncontrollably into a fetal position. “Wait, wait”, I say, “there’s good news: I have a plan”.

Exercise shock

T-37 days to hike

A superpower I’ve had since childhood is to be able to obsess over things, sometimes to my detriment, but most times for my own benefit. When in that state, fears and distraction are bypassed, and over the years I learned to channel that. Call me a nerd, but if concentrate in certain ways on an end-goal, I can turn on a kind of robotic discipline to get there. I can’t explain why it works for me, but this ability helped me in key moments, from school and studying how to fix my lactose intolerance, to building my own company and getting clients in the US.

That obsession kicked in this week in full force. Once the reality of my miscalculation settled that Wednesday night, my mind could only see a picture of the mountains around Hongu with their lush forests, the carpets of stone laid out through dense cedar and cypress forests, guiding pilgrim’s walks for thousands of years. I felt that the imagination, despite far into the distance, could someday be a reality in front me.

My hatred for exercising vanished the next morning. There was no procrastination, and the concept of pain felt secondary. I suspect that’s a tiny bit how people like David Goggins feel when running endless marathons. While I’d have given up sooner when lifting weights, that day I kept pushing to the final count while the Hongu Taisha Otorii flashes blinked in my mind. The exercising process had ceased from being an end in and of itself, and became a conduit, a means to a greater end. I had never felt that towards gym.

Whenever thinking about the exercising I’d need to do, that thought was overlaid with the trail image I had to walk, all its tree roots and the rocky steps.

How much trouble am I in?

On August 22, I head to the ground floor after a workday, carrying my 1L sling bag with a water bottle, and start the climb. The first few floors go untroubled. After the 19th floor, I start breathing heavily and I need to be proactive about the rhythm. The soreness from yesterdays’s workout joins me again, as if mocking my ascent. I laugh back.

My lower glutes punch me at every step. After every loop, I head down via elevator to preserve my knees (my focus is gaining muscle, not damaging my joints). After the 47th floor, small 20-30s pauses for breathing are necessary. The fight is ending, and after 37min, I complete 89 floors.

Eighty-nine-floors. It might look like nothing to you, or a lot, but I had not clue what to expect. I’m both jubilant that my first session finished above the No-Go threshold, and worried that it’s below the Minimum. All in all, this is August 22, not September 22, so I’ll keep my judgment in suspension for another month, but it looks much more doable and less scary now.

I laydown ice bags with trembling legs for my precious glutes.

Travel starts

We travel to the United States for a wedding over the weekend in Minneapolis. The general plan is spending a week in San Francisco and two in San Jose. Training will resume anywhere possible.

A lost week

I get sick and stay stuck in a hotel room. 25 days to walk.

[TODO] Sep 1, Mon: we get in San Francisco (Sun) and it feels like some allergy is brewing. Allergies are part of my life, so I don’t think much about it, I just swallow a pill. The runny nose and watery eyes get worse and worse. The pill goes completely ignored and the situation gets worse by the hour. The “allergy” turns out to be a full blown cold / flu.

On Tuesday, I’m able to get some work done, but end up in bed until 7pm. Wed, Thu, the entire week goes by without any exercise possible.

Friday finally gave me some breathing room for a reset, and I walked that day about 3 miles. I was weak and every step felt like a carrying a large boulder in my backpack.

San Francisco
I get sick on Labor Day, a holiday in the US. We stay stuck in the hotel for a whole week. Five days later, 21 days to the walk, I’m able to finally take a stroll outside for a little longer than 4km without feeling like my body is falling apart.
I am not productive for the whole week

Our next destination is San Jose, California, where we will stay for two weeks. The Airbnb is located in a nice and convenient area in Santana Row.

San Jose: back to square one

21 days to walk.

The bus speeds through San Jose, I see a repetition of blocks and houses that all look the same, like if we were walking in circles. The endless suburb is tidy and organized, no trash on the streets, lush grass, and cars. Lots of cars.

Cities in America aren’t made for walking. You either hit some area lacking a sidewalk, or you find yourself suddenly walking on a highway, and your ears work non-stop for the tires on the tarmac. Training just isn’t fun.

I Back hurts [todo] “What you’re describing (tired, achy mid-back muscles next to the spine, not sharp or ‘injury pain’) sounds like muscular fatigue from postural stabilizers — the muscles that keep your torso upright”

[todo]

The last mile

We land in Colorado for the last week before the walk. Over the weekend we take a short walk through the Garden of the Gods.

I’m optimistic we’ll have a good time next week. My back still hurts after long walks with a backpack, but it’s manageable. My legs are doing their job well so far, to the extent I have tested them. However, most of the training has been on flat surfaces or in the gym, so it’s time to go out there and start hiking more complex surfaces.

In Vail, on a Tuesday afternoon, we head to the Son of the Middle Trail, a 3-hour walk uphill through a color palette of yellows and greens. It’s raining and muddy, but the spirit of adventure is more intense than the annoyance. I’m not alone, so in any event there is support.

The initial climb feels… tiresome. I’m shocked at how much of a bad state my breath is, I’m gasping for air. I recall, though, that Vail’s altitude is 8,150 ft, and I feel less bad about it. I start to wonder, however, whether having embarked on this trail was a good idea at all.

My legs keep trucking along like soldiers on a march. After 850 ft of elevation gain over 2.5 km, though, I finally start feeling glutes. I’m fighting for air, breathing keeps getting harder and harder.

At the 50 minutes mark and 980 ft of elevation gain (300 m), I assimilate how that much is similar to Day 1 on the Kumano Kodo, from Tajikiri to Chikatsuyu, except there it’s 3x the elevation gain and 13km. Here, I barely walked 2.8km.

There’s a kind of spiritual sensation when you are in a primitive environment like this. You face your primitive sensations, your primitive struggles to keep going when your muscles are crying out for a break, all while you are applying just the necessary mental concentration to make sure you’re step on the right spots, on the right rock, on the right fallen branch, beside the mud.

It makes you appreciate the modern life, how far we’ve come as a society. All this mental focus through struggles was once how we kept moving through tremendous distances to grab a bucket of water for our families. The physical movement is a mental training as much as it is for the muscles.

After an hour or so, 3.2 km and 1120 ft of elevation, a flat section that makes my legs feel like they are resting. Movement that feels like a pause. A mere 30 seconds on level ground is enough for my muscles to smile.

My left foot starts hurting after about 70 minutes. I become more intentional about what I’m doing with it. The mindfulness means throwing my foot in the air so that the movement serves as micro-massage, leaving my leg more flexible than before. That is enough for a while, and the pain subsides until I need to start climbing again, which requires making my foot stiff to sustain my body on the ground. This dynamic of pain followed by relief, followed by pain continues for another 20-30 minutes. I guess it got more relaxed after a while?

The hike continues for another hour, no more pain, my glutes are fine, my legs are marching along and I’m just used to the walk. I get into a tunnel vision and just enjoy nature.

The walk comes to an end. I’m back at the hotel. Maybe tomorrow I’ll do it all over again. Or should I?

Tokyo to Kyoto to Tanabe

We land in Tokyo after a sleepless 12h flight and travel straight 3-4 hours to Kyoto, where we will sleep. We arrive 8pm and go shopping for hiking gear around the station until 9pm, along with our heavy luggages. We move hiking gear to our backpacks and get to bed. Next morning, we ship our need to

[todo]

[TODO] 2025-09-28 Estamos bem, chegamos mortos ontem. 21h de viagem depois de ter dormido 4.

Acordamos 5:50 e estamos arrumando mochilas e tal. Vai chover então alguns planos precisam ser ajustados.

7:30 agora, pausa pro café. Depois, finalizar malas para despachar para o hotel que chegaremos em 7 dias. Cada dia é crítico e se a gente não conseguir chegar no destino, gera uma reação em cadeia bizarra 🥲

Hoje vamos pra Tanabe onde o chef aquele vai nos pegar de carro, e vamos dai pras montanhas. Caminhada começa amanhã.

Problem-solving template

2025-06-22T14:00:00+00:00

The following is a template for RFC’s and Tech Briefs I’ve been using since 2013 in startups for change proposals and aligning understanding among engineers and business people.

Why would we use such a template?

We engineers tend to over-optimize for solutions (to engineer literally means “find solutions”). In that process, we sometimes forget to think deeply about the problem, especially when we’re passionate about the solution. Lots of engineers jump to resolution without fully understanding the problem, and/or without communicating their understanding to those around, generating more problems in the process.

To interrupt that bias, this template serves as a sort of checklist while also giving structure to the very solution. Forcing the writer to think deeply about the problem before diving into a solution optimizes for rationality and maximizes changes of success.

↘︎ Skip to template

Think of it as a starter kit. You can get a lot more sophisticated. For example, under the Problem section, you could include user stories, data, and anything that details it, but you’re free to omit that depending on your situation.

Some tips:

The best documents are the shortest. Inexperienced people don’t write docs, but when they first see their value, they write bibles. After a few years and seniority, they realize most of it is noise, and then they start writing short but good documents.
Get feedback on your first draft, to make sure you’re going in the right direction. The best professionals do.
I’ve used Github for reviews for years, and more recently people have preferred UI’s like Notion, which in you can comment on specific sentences. That’s secondary, but interacting and iterating on the document should be fast.

The template

tl;dr {write this after the doc is ready}

{Small 1-2 sentences introducing this document.}

# Problem

{
Explain the problem. Start from high-level to low-level, creating anchors for the reader.

Take the reader background into consideration. For engineers, focus on technical. For a non-technical audience, start with non-technical language to orient them.

If you can't explain it, you don't understand the problem. Don't jump to solutions before you understand it and the constraints.
}

# Objectives [optional]

{
Describe what you aim to achieve with the solution below. Do we want to hit a specific number? Do we want to decrease a particular threshold?

This section can grow into subsections and include metrics (usage, performance), as well as business objectives, especially for Product briefs. For Tech briefs, they tend to stay focused on systems.

Why [optional]? Because most everyday problems are simple and the Problem section will already make the goals self-evident. Sometimes, however, the problem is large and you want to tackle only a piece of it. In those situations, it makes sense to say, "hey, we will attack this corner over here" to help the reader understand why your propose change is so brief is relation to the problem space.
}

# Proposed change

{
List here every change you are going to make, separated by system. If you are touching two systems, add sub-sections for each.

Most readers are visual, so make use of pictures, charts, diagrams and tables where possible. If you got bullet-point with sub-bullet-points, reconsider if that can become a table.

Architectures and structures that take 2 minutes of reading to understand can be visualize in seconds with a diagram. These days, Github and Notion support Mermaid so creating visual cues is easy, so no excuses.

If you're dealing with a large problem and you need multiple solutions, create separate documents for each solution. For a large problem, e.g "Observability", you might want proposals "Metrics", "Lifecycle map", "Dashboard" and so on.

Rule: do not include alternatives. Your goal is to synthesize the problem and come up with a single solution. There's a whole section at the bottom for alternatives.
}

## Release plan [optional]

{
Usually bullet-points.

For more complex changes, you might need to release parts of it behind feature flags to decrease risk. Make sure to list them here, as well as the timeline. You can use tables to help the reader visualize the content.
}

# Drawbacks

{
Bullet-points with tradeoffs. What's not so great about the proposed solution? What issues aren't addressed?

This section signals to the reader that you considered the shortcomings and had a more holistic view of the problem-solution. You can also include what would be required to "fix" each drawback (in Pros-Cons-Fixes style).
}

# Alternatives

{
List approaches that aren't being proposed but were considered. This gives the reader a chance to review your understanding of the problem, and also signals you considered all alternatives.

Make sure to include why each alternative isn't the main proposal.
}

My universal coding prompt (Claude Code, Cursor and others)

2025-06-22T14:00:00+00:00

This universal prompt for Claude Code and others has greatly improved my AI usage for coding tasks. Before, my totally-non-scientific scoring of Claude Code would sit around 5-10% useful. Now, its usefulness rose to 85%+ and has become a tool I use everyday during development.

If you’re in a hurry, tl;dr copy the prompt at the end of this post and put in ~/.claude/CLAUDE.md, which is location Claude goes to regardless of project you’re in.

↘︎ Skip to prompt

What’s behind this prompt?

It compacts information by referencing books. The more tokens you add to the context window (aka your prompt), the more dilluted the overall instruction becomes. By referencing books, though, we elicit all those concepts without having to take up all that space. It’s like referencing memory vs copying memory.

You’re welcome to swap with other books if you dislike any of them, but these are the ones that I found to be some of the most impactful since the 2000’s when it comes to software design. For example, I’m not religious about Single-Responsibility Principle (SRP), but I’d rather the LLM organize files in several drawers with nice and meaningful names than defaulted to using a single file for everything. Or I’d rather it avoided mocking things we don’t have control over.

Architecture and process over language techniques. LLMs are pretty good at recalling your favorite language function and bad at following a development process that is sound. It never asks questions to understand the problem and is keen on jumping to conclusions quickly (like some junior developers). That’s understandable, given default prompts must work for the average user.

The prompt below focuses predominantly on the development process, on problem-solving practices that go beyond software engineering. When we reference Clean Code, we’re trying to elicit those concepts of organization and formality that you won’t get if you were just telling it how to name variables.

Guardrails with orientation for problem-solving. In any conversation, understanding can be verified when the listener repeats back to the speaker what they heard so the speaker can confirm it (e.g steelmaning). LLMs are especially prone to skipping that verification part, coming up with understanding that may or may not be our intent.

To circumvent that, the backbone of this process is, “1. Think Before Coding […] 2. Ask Questions First […] 3. Share Your Plan […] 4. Incremental Development [40-50 lines max]”. By forcing it to ask questions, we embed a sense of curiosity that isn’t there on average conversations. After all, LLMs being primarily generative means it won’t stop until it finds a stopping point, and we give it one with questioning.

Not coincidentally, this approach is what we come to expect in engineering interviews over the years. When human candidates jump to coding without questions, except in rare situations, it generally indicates they lack the instinct to fill in intent/communication gaps that might occur between them, PMs and others. It’s a red flag for humans, much more so for an LLM.

We also expect humans to share their plans. Junior developers need to share it ahead of time so coworkers can make sure they’re going in the right direction, while Senior ones do that because they learned from experience that they’re fallible human beings and need a second pair of eyes. Peer review at the heart of the process.

Braiding concepts throughout the prompt. The books we mention in paragraph one are also mentioned again in the last section, and the sense of humbleness mentioned above is called for multiple times.

We braid concepts throughout the prompt, getting back to it later. Around the middle of it, “When stuck on tests, if you’re unsure how to make a test pass or tempted to skip testing […] 1. STOP and ask for guidance”. I don’t have proof, but I suspect that repeating this pattern throughout the prompt elicits more attention to this particular concept, like . In practice, it has worked wonders, drammatically increasing the output quality.

How does it align with prompting best practices?

Before the final version, I asked ChatGPT’s Deep Research to describe the best practices from the industry, and I fed it various links to articles and papers on the subject.

Once the research was done, in that same chat I gave o3 several bullet points with specific instructions I wanted it to follow, including books, the problem-solving process, and it embed those within the best practices.

The prompt

Put it in ~/.claude/CLAUDE.md. Copy and use it as you’d like. I’m curious about the improvements you’re going to make.

You are an expert software engineer with deep knowledge of Rails, JavaScript, and modern software development practices. Your approach mirrors the wisdom found in these essential texts: “Growing Object-Oriented Software, Guided by Tests” by Freeman & Pryce, “Clean Code” by Bob Martin, all books by Sandi Metz, “Data and Reality” by William Kent, “Thinking in Systems” by Donella Meadows, “Making Work Visible” by Dominica DeGrandis, “The Pragmatic Programmer” by Andy Hunt, the Software Delivery in Small Batches podcast, and all content by Gary Bernhardt.

## Core Development Philosophy

### 1. Think Before Coding

Before writing any code, you MUST:

- Break down the problem into its smallest logical components
- Identify unclear requirements and edge cases
- Design the architecture at a high level
- Plan the implementation approach
- Consider potential risks and mitigation strategies

Never jump straight into coding. Always think first, plan second, code third.

### 2. Ask Questions First

When presented with a new feature or problem:

1. DO NOT start coding immediately
    - Except if already answered in the prompt.
2. Instead, ask clarifying questions about:
    - Input/output formats and examples
    - Performance requirements
    - Error handling expectations
    - Integration points with existing code
    - Edge cases and boundary conditions
    - Non-functional requirements (security, scalability, etc.)

Use this format:

    Before I begin, I need to understand a few things:
    1. [Specific question about requirement]
    2. [Question about edge case]
    3. [Question about integration]
    ...

### 3. Share Your Plan

After understanding requirements, ALWAYS present your implementation plan:

    Here’s my proposed approach:

    ARCHITECTURE:
    - [High-level component design]
    - [Data flow]
    - [Key abstractions]

    IMPLEMENTATION STEPS:
    1. [First small increment]
    2. [Second small increment]
    3. [Continue...]

    NAMING PROPOSALS:
    - Classes: [proposed names with rationale]
    - Key methods: [proposed names with rationale]

    RISKS:
    - [Potential issue]: [Mitigation strategy]

    Does this align with your vision? Any adjustments needed?

### 4. Incremental Development

- Implement features in small, focused increments
- Each increment should be 50-60 lines maximum
- After each increment, explain what was done and why
- Ask if you should proceed before continuing
- Never dump large blocks of code
- If you replace some call with a new method, remember to remove the old one

Example workflow:

    Step 1: I’ll create the basic class structure with initialization
    [20 lines of code]
    This establishes our foundation. Should I proceed with adding the validation logic?

    Step 2: Now I’ll add input validation
    [25 lines of code]
    This ensures data integrity. Next would be the core business logic. Continue?

## Testing Requirements

### Test-Driven Development is MANDATORY

- We ALWAYS write tests
- Tests come before implementation when possible
- Every piece of functionality must have corresponding tests
- No code is considered complete without tests

### When Stuck on Tests

If you’re unsure how to make a test pass or tempted to skip testing:

1. STOP and ask for guidance
2. Never comment out or delete failing tests
3. Never ship untested code
4. Ask: “I’m having trouble with [specific test]. Here’s what I’ve tried: [attempts]. What approach would you recommend?”

## Code Quality Standards

### Naming Conventions

- Classes: Use nouns that describe what they represent (e.g., `OrderProcessor`, `UserValidator`)
- Methods: Use verbs that describe what they do (e.g., `calculate_total`, `send_notification`)
- Variables: Use descriptive names that reveal intent
- NEVER use generic names like `run`, `call`, `execute`, `do_work` without specific context

### Method Design

- Keep methods small (5-15 lines preferred, 20 lines maximum)
- Each method should do ONE thing
- Extract complex logic into well-named private methods
- Prefer many small, named methods over few large methods with comments

Example (Ruby):

    # Bad
    def process_order(order)
      # Validate order
      if order.items.empty? || order.total <= 0
        raise InvalidOrderError
      end

      # Calculate tax
      tax = order.total * 0.08

      # Apply discount
      discount = 0
      if order.customer.vip?
        discount = order.total * 0.1
      end

      # ... more logic
    end

    # Good
    def process_order(order)
      validate_order(order)
      tax = calculate_tax(order)
      discount = calculate_discount(order)
      finalize_order(order, tax, discount)
    end

    private

    def validate_order(order)
      raise InvalidOrderError if invalid_order?(order)
    end

    def invalid_order?(order)
      order.items.empty? || order.total <= 0
    end

    def calculate_tax(order)
      order.total * TAX_RATE
    end

    def calculate_discount(order)
      return 0 unless order.customer.vip?
      order.total * VIP_DISCOUNT_RATE
    end

### Instance Methods Over Class Methods

- Default to instance methods for better testability and flexibility
- Use class methods only for true class-level concerns
- Consider if behavior belongs to an instance of the concept

### Code Style

- Use spaces, not tabs
- 2 spaces for Ruby/JavaScript indentation
- Use consistent quotes (prefer single quotes in Ruby/JS unless interpolation needed)
- Follow language-specific conventions (snake_case for Ruby, camelCase for JS)

## Rails-Specific Guidelines

### Separation of Concerns

- Models (app/models): Database persistence and associations ONLY
- Business logic: Lives in service objects (app/services) or domain objects (lib/)
- Controllers: Thin controllers that only handle:
    - Request parameter processing
    - Calling appropriate service objects
    - Rendering responses
    - HTTP-specific concerns

### Service Object Pattern

Example in Ruby:

    # app/services/orders/process_payment_service.rb
    module Orders
      class ProcessPaymentService
        def initialize(order, payment_method)
          @order = order
          @payment_method = payment_method
        end

        def call
          return failure(:invalid_order) unless valid_order?

          charge_result = charge_payment
          return failure(:payment_failed, charge_result.error) unless charge_result.success?

          update_order_status
          send_confirmation_email

          success(@order)
        end

        private

        # Small, focused private methods...
      end
    end

## JavaScript/ES6+ Guidelines

### Modern JavaScript Patterns

- Use `const` by default, `let` when reassignment needed, never `var`
- Prefer arrow functions for callbacks and functional programming
- Use destructuring for cleaner code
- Implement async/await over promise chains
- Leverage ES6+ features appropriately

### Functional Programming Preferences

- Favor immutability (use spread operators, avoid mutations)
- Use pure functions where possible
- Compose small functions into larger operations
- Avoid side effects in core business logic

## Communication Style

When presenting code or solutions:

1. Start with the “why” - explain the reasoning
2. Present code in small, digestible chunks
3. Highlight key design decisions
4. Point out tradeoffs made
5. Suggest alternatives when relevant

## Error Handling

- Always include proper error handling
- Use custom error classes for domain-specific errors
- Provide helpful error messages
- Consider recovery strategies
- Log appropriately for debugging

## Questions to Always Ask Yourself

Before submitting any code:

1. Is this tested?
2. Would I be proud to show this to Sandi Metz, Gary Bernhardt, or Bob Martin?
3. Can this be broken down further?
4. Are the names intention-revealing?
5. Does this follow the Single Responsibility Principle?
6. Is this the simplest solution that could work?

Remember: We’re craftspeople. We write code for humans first, computers second. Every line should be deliberate, tested, and maintainable.

The Space Between Yes and No

2023-08-12T19:00:00+00:00

We humans tend to perceive the world as a series of yes/no answers. Limited questions nurture limiting beliefs. Our questions yield black and white answers.

It used to be ok to think in simple terms. If you were alone in the forest 12,000 years ago and heard a cracking sound of wood breaking, you should decide quickly whether to run or not. It could be a leopard. There was no gain in anything other than yes/no. You better run 100% of the time.

In today’s world, though, thinking through yes/no is far from ideal. Civilization got here by sieving through nuances. In the last 150 years, science and engineering shaped our new reality through the discovery of penicillin, relativity, telecommunications and the internet, mobile phones and AI. Consider the development of weather forecasting, a field that relies heavily on probabilistic models. Meteorologists don’t simply ask, “Will it rain tomorrow?” but rather, “What is the probability of rain given the current atmospheric conditions, wind patterns, and temperature?”

The world is a space of random possibilities with different degrees of probabilities. There’s a 50-50 chance a coin will fall on either side. There’s a 75% chance that I will have ice cream this week because there’s also a chance that I will get sick or it’ll be cold. There’s a 98% chance we will see a revolutionary new technology announced this year, and there’s a 1% chance we will see civil unrest.

These probabilities change constantly, and are chained to other probable and improbable events. There’s a 20% chance it will rain, and if it does, there’s a 95% chance I will have to drive to my destination instead of cycling.

Yes/no questions box us in, they limit us. Let’s consider two questions you can ask yourself to assess a situation at work:

Will this project be delivered in 30 days?
From 0 to 100%, what is the probability that this project will be delivered in 30 days?

The second question is a lot richer than the first one. You might feel like you’re 90% confident, which could mean “yes” for a lot of people, but 90% is still not a “yes”, 90% is still uncertain. “90%” begs the question, “what 10% of it is undermining our confidence?” It also gives us space to attribute different probabilities for different dates, you can feel 20% confident that it’ll be delivered in 20 days, 40% in 25 days, 60% in 30 days, and 95% in 40 days. 100% sure it won’t go over day 50.

That is how I communicate with my clients/bosses or whoever I do business with. “When will it be delivered?” is replied with three estimates, an optimistic (e.g 25 days), a pessimist (50 days) and a realist (40 days). This shares the risk and transfers the conversation from a mere contract negotiation to collaboration.

I was once approached by a company that wanted me to move close to their office, and a friend asked me, “Would you move to that city?”, and I pondered, “would I”? This got me thinking on both, “Yes but I feel uncomfortable” and “No, but I’d be shutting down opportunities”.

And then it hit me that a much better question would have been, “What are the probabilities of moving to that city given the various aspects of the offer?” Every benefit adds a higher probability of moving. Under the offer? 0% chance. Maybe if they paid a premium we could get it to 30%, but would still be bad. Maybe if the role was specific and the offer included better equity or compensation it could move chances to 80%. But maybe including the family variable it could be lower.

I’m fairly confident you got the point (maybe something around 85%). It’s not that we won’t have yes/no answers, but it’s that questions are what fuel our creativity and we rather start well, with good questions.

What does bang methods mean in Ruby?

2023-03-02T10:00:00+00:00

The Ruby convention for using bangs (!) is, mostly, “when there are two versions of the same method, and one of them is more dangerous than the other, use the bang”. Citation is none others than Eric Hodel and David Black.

For example, in Rails there are update and update!, create and create! and so on. In Ruby’s Enumerable there are map and map! and others, but note that’s always two methods with the same name. If we check https://ruby-doc.org/3.2.1/Enumerable.html, not a single method has only a bang method, they all come in doubles.

The bang in Ruby has nothing to do with whether the method raises exceptions. Array#map! doesn’t raise an exception. On the other hand, ActiveRecord’s create can raise exceptions, like when you set uniqueness constraints on your database. However, you sure could use it to mean that the method raises an exception, but that will be your meaning, and it’s fine. Just be careful not to confuse others.

It also doesn’t doesn’t mean that it mutates self. Most Enumerable methods with bangs mutate themselves, and that’s just a coincidence. ActiveRecord’s create also mutates itself, and has no bang.

The bang doesn’t mean “it is dangerous”, it means “it’s more dangerous than the counterpart method without bang”, and so unless there’s a second method, I don’t quite get why put the bang. The presence of def delete! means that there’s an equivalent def delete, but if we can’t find it in code, not even in mixins or parent class, then that causes confusion.

And maybe it’s fine to have the bang in methods without counterparts, but what does it mean in this case? Just make sure you have a convention with your team, and make sure every new member who joins is notified that the Ruby convention for bangs is not being used. But at that point, it might not be worth the hassle, and it might be simpler to just stick with known conventions.

Remove Distractions From Websites

2023-02-19T10:00:00+00:00

Some friends use Instagram as primary chat app. Whenever I open it, I’m sucked into a swirl of content. Some times it pulls me for several, several minutes until my mind steps back and realizes what’s going on.

The solution I found was using Instagram on my Mac and inserting arbitrary CSS into its page to strip out everything that is not chat. The image below is what Instagram looks like to me. Notice how there are no menu, no Explore, no Search:

I have a shortcut that takes me directly to https://www.instagram.com/direct/inbox/ whenever I want to check what’s going on. If you think about it, you could even turn on chat notifications if you wanted without fear of falling into traps by advertisers. This should work with other websites like Twitter and Youtube as well.

Ok, so how do I do it?

I use Safari and there’s a cheap app called Cascadea that allows us to insert CSS into webpages. If you’re on Chrome or Firefox, you’ll have way more options by looking at the Chrome extension store.

This is the first CSS version I used to get it working:

div.xh8yej3.x1iyjqo2,
div.x1cy8zhl.x9f619.x78zum5.xdt5ytf.x1gvbg2u.x1y1aw1k.xn6708d.xx6bls6.x1ye3gou.xvbhtw8.x1xgvd2v.x1o5hw5a.xaeubzz,
a[href='/explore/'],
a[href='/reels/videos/']
{ 
	display: none; 
}

Instagram’s HTML has a lot of gibberish CSS classes. I suspect they’re going to keep changing over time to break this type of script. Anyway, I added a rule to check for href for Reels and Explore and that seems to be enough in case other CSS rules change.

Visto Japonês como Brasileiro

2023-01-31T10:00:00+00:00

Não sei se é só comigo, mas a experiência de tirar o visto japonês é aterrorizante. Já voei mais de 400.000km, não-sei-quantos-países, mas esse visto me tira o sono.

O fato de você precisar comprar uma passagem aérea não-muito-barata antes de pedir o visto é brutal. Imagina você comprar uma passagem de R$5.000, talvez o dobro se for com o cônjuge, pra ser rejeitado por motivos bobos como sua foto ter ficado na proporção errada.

Eu vou focar em alguns detalhes que não achei facilmente em outros sites. Se você quer a lista completa de documentos que precisa, melhor pesquisar noutro lugar.

Vamos às dicas:

escreva uma carta ao cônsul: já fiz 3 pedidos de visto, e nas 2 que foram aprovados eu havia escrito uma carta ao cônsul (ou embaixador se você estiver noutro lugar). É só um texto impresso dizendo que amo o Japão, a cultura, e quero poder vivenciar o país etc. Tudo muito abstrato, sem nada definido. Isso deve ajudar bastante porque é um elogio forte ao país associado ao seu pedido, não só documentos de identidade. Na primeira vez eu fiz à mão, na segunda pedi pro ChatGPT escrever pra mim.
leve a certidão de casamento: se é casado, não esqueça da certidão de casamento. Vi muitos casos de pedido negado por causa disso.
considere uma reserva de passagem sem comprá-la: o consulado pede que você compre uma passagem antes do pedido, portanto essa dica é por sua conta e risco. É possível reservar uma passagem por $14, a qual é automaticamente cancelada depois (detalhes abaixo). Eu fiz isto no terceiro pedido e funcionou, mas todos os sites da internet dizem que não funciona. É possível que eles tenham ignorado isso por eu já ter ido antes no Japão? Sim, mas não tem como saber porque eles não são abertos sobre o processo.
tenha reserva de avião de todos os trechos: eu queria sair de San Francisco/US, e comprar a passagens do Brasil pra lá só mais perto da viagem. Só depois de reservar minha passagem é que descobri, lendo comentários em blogs, que eles não aceitam que esteja faltando reservas desde o Brasil. Tive de reservar novamente antes de ir no consulado, correria total. Você está na Ásia e pensando em ir pro Japão? Vai ter problema com visto se não tiver todos os vôos já reservados.
use Booking.com para hotéis: assim como passagens aéreas, você precisa das reservas de hotéis. Isso você faz no Booking.com sem esforço e sem pagar. Os quatro hotéis que reservei ficaram lá reservados por meses, e depois cancelei.
formulários são confusos, mas use-os: embora os PDFs que você tenham que baixar para preencher sejam muito, muito antigos, use-os. Claramente as instalações dos consulados são antigas. As mesmas revistas que vi na sala de espera em 2012 estão lá ainda em 2023! E consequentemente, esses PDFs são a linguagem do pessoal que trabalha no consulado, então se você tentar usar outros formatos, é melhor que seja familiar senão você pode acabar simplesmente tendo seu pedido negado.
não precisa imprimir os PDFs para preencher: no seu computador, você pode editar o PDF, escrever texto por cima. É muito melhor digitar no documento e ao final imprimir, você vai ser muito mais rápido assim.
prefira uma entrada no Japão: é possível pedir um visto onde você sai do Japão, visita outra lugar e depois volta, só que ele é 2x mais complicado, afinal você precisa ter todas as passagens. Imagina você comprar sua passagem de Tokyo para Seoul, e de volta para Tokyo, e ter seu visto negado? Eu particularmente não faria esse tipo de visto. Visto de uma entrada é suficiente pra grande maioria das viagens.
“A regra não é clara”: você não vai saber todas as regras porque o consulado não é claro. Você vai ter que ler muito comentário de blog pra entender como os fiscais julgam cada caso.
mostre que você tem renda: inclua documentos PJ, contratos de trabalho, extratos, recibo de IRPF, talvez IRPJ também se você é autônomo. Se você não nada de dinheiro provavelmente vai ter o pedido negado.
use o ChatGPT para o itinerário: porque de outra forma você vai levar horas criando uma lista de lugares para visitar. O consulado pede isso, e pede que você preencha num PDF bem antigo. A beleza da coisa é que você pode apresentar esse itinerário, mas depois ir em lugares completamente diferentes. Pois o ChatGPT cria esta lista em 10 segundos enquanto você vai levar 20 horas manualmente.

A Reserva de Passagens com PNR

Na minha segunda ida, eu queria evitar comprar uma passagem antes do visto. Então resolvi arriscar e criar uma reserva na Onward Ticket.

A Onward Ticket reserva pra você uma passagem para você por 48 horas, com preço de $14. Ela tem um código PNR que é verificável em sites de companhias aéreas, então o pessoal do consulado pode verificar sua reserva. A alternativa seria comprar uma passagem por mais de R$6.000 por pessoa, e jogar roleta da sorte. Nesse caso era pior ainda porque queríamos ir de business class (encontramos umas promoções com valor próximo a econômica).

Na primeira que vez que tirei meu visto, pediram 2 dias para revisar o visto, mas desta vez, para meu choque, pediram 7 dias! Isso significa que é necessário ir no consulado imediatamente depois de pegar as reservas, ou seja, compra a passagem de manhã cedo antes de ir no consulado pra ter uma intersecção maior dos dois prazos. Isso me causou uma ansiedade absurda porque eu moro a 3 horas da cidade do consulado, e certamente a reserva expiraria e eu seria negado.

Felizmente, quando peguei meu visto, que foi aceito, a data de aprovação era exatamente 2 dias após minha entrada. Em outras palavras, eles revisaram minha passagem em seguida, pouco antes dela expirar. Por pouco não sou negado.

É realmente importante que a reserva seja real?

Sim, segundo muitos comentários em blogs de pessoas que foram negados por causa disso, mas no meu caso uma reserva PNR foi suficiente. Por isso esta dica é por sua conta e risco. Se você não se sente confortável, melhor comprar uma passagem.

Meditation

2022-12-17T08:00:00+00:00

When I meditate, my mind calms down. I start in the midst of chaos, but I finish in total control, ready to conquer.

As I close my eyes and start the session, my brain continues its automatic course, pulling new ideas and threads, ignoring my intention. It brings me memories from work, new propositions, deadlines, things I forgot to put into my to-do list. It gets slightly anxious.

I realize these automated thoughts after a few seconds of delay, and then intentionally put my focus on my breath. I stay there for a few seconds. I notice the physical aspects of my chest moving back and forward. I stay grounded. Temporarily.

A sudden sound far away impels my mind again. Random questions pop into my head, but I gently remind it that we aren’t here right now to think, to ponder, to imagine, to get anxious about the future, to remember the past, but solely to enjoy the present. My mind surrenders. I am in control again. I am in the present, I am the present.

But then, suddenly, the mind starts to wander, and periods of focus are followed by periods of thinking and worrying. This repeats multiple times throughout. In reality, the mind is a wild horse, quickly responding to fight-or-flight impulses, uncontrollable, but we need to be patient, gently pulling the rope tossed around its neck whenever it acts abrupt or independent. We have to domesticate it. When arbitrary thoughts pop into my mind, I bring back my focus into breathing.

The session ends. I open my eyes and there is only what’s immediatelly in front of me. There are no forced thoughts, no anxiety, no imagination. Just peace. Like the end of a massage session, or a floating capsule. A blank slate, a white board, I am free to think whatever I want or need to.

The day ahead of me awaits with many traps and challenges, but I am ready to conquer.

***

Years ago, I used to need several, several minutes of meditation until the internal battle with my mind would settle. It would parry my efforts, only to lunge back into controlling me - back and forth, many times. But over time it would retreat back and surrender. Today, I might need only 5 minutes to end the dispute, some times more, some times less.

When I forgo meditation for months, I notice the deterioration in the quality of life, in my peace of mind, in my control over whatever wants to control me. I become less stoic. I forget meditation even exists. The everyday events affect me before I can have a say. My mind seeks short-term rewards to get through the anxieties of the day. It procrastinates. It binges on sugar, on breaks, on the news. I am responsible, but those are not my decisions.

When I meditate again, I have a helicopter view of life. My choices are in front of me, and I choose to be affected or not by thoughts. It’s not as if I won’t feel bad feelings the days I meditate, they will definitely come. The difference is that when I do meditate, those intrusive feelings are put on a desk in my mind, like papers waiting for my review. I look at them and I have a choice to say yes, or to say no.

I found there are other ways of achieving some of the effects of meditation. Driving, being in nature, looking at the horizon, sitting by the shade with wind blowing in my face - or turning on Do Not Disturb. There are certain songs that transport me to other universes. But none of them have this effect of transporting me to the present as effectively and immediately as meditation.

Generate CSV from Rails console (Heroku)

2022-11-19T10:00:00+00:00

Config the following file and save it with some name file.rb:

report = CSV.generate do |csv|
  csv << ["name", "email"]

  users = User.where(
    :created_at => Date.parse("01-11-2020")..Date.parse("30-11-2020")
  )

  users.each do |user|
    csv << [user.name, user.email]
  end
end

Method One: Pipe Into a File

Add the following at the end of the code:

STDOUT.puts report

Then run the following in the terminal:

cat file.rb \
  | heroku run --no-tty --app=heroku-app-name -- bin/rails runner - \
  | grep -v "\*\* \[NewRelic\]" -v "DISABLE_DATADOG_AGENT" \
  > results.csv

where:

cat file.rb: reads the code for piping into Heroku or some other Rails console process
heroku run ...: the console itself. It could be another console (e.g AWS, GCP or local). --no-tty is used for preventing characters used for user interaction. Replace --app with the name of the app.
grep ... NewRelic: this removes those annoying booting lines from 3rd-party libs in Rails.
> results.csv: write the results from the Rails console into a CSV file.

Method Two: With Slack

If you have an array like in the original, you can

Slack::Web::Client.new.
  files_upload(
    channels: '#some-channel',
    content: report,
    filename: "file.csv"
  )

Roadmap for One-on-One’s

2022-10-31T10:00:00+00:00

These are foundational topics for one-on-one’s. They are the first ones I bring for discussion every week to set out the background for the relationship that will follow. They are not the definitive list of topics for one-on-one’s, but the most important ones for starting out.

Some subjects are about meeting in the middle and learning about each other. On the other hand, some are about being upfront and making some soft-promises to reassure them that you are worth their time. That is a double-edged sword because on one side, it can be dangerous if I fail, but on the other, it gives me focus on deliver on the promised. And promising and overdelivering is a powerful weapon.

Each topic is meant for a different one-on-one because they can be dense. It’s ideal to keep each opportunity to one concept at max. However, some are quickies and can be slotted alongside others.

All in all, our relationship is an enabler and core to our success. Relationship is, therefore, a recurring theme throughout.

The List

The following markdown-formatted list can be copy and pasted in most todo apps.

- [ ] Meta 1-1: So why do we do one-ones? As a developer, I didn't understand 1-1's, but as a manager I finally do, so I'd like to discuss how to make them productive. Whom do 1-1's belong to? To reports. Who sets the agenda? Reports. I'm a facilitator. If you're struggling to articulate concerns, I'll help you. If you don't know what to set as agenda, I'll help you.
- [ ] Meta 1-1: my responsibilities on direction, coaching and career development.
- [ ] I don't judge feelings, frustrations and impulses. We're humans and we all have it. My opinions are held in suspension. What really matters is what we decide to do about them.
- [ ] Meta 1-1: on feedback (e.g observation)
- [ ] Quickie: questions are not requests.
- [ ] Proactive Alignment.
- [ ] Meta 1-1: walking one-on-one's and audio-only calls.
- [ ] Quickie: on alignment; on not saying "I understood" until the message was actually understood.
- [ ] Meta 1-1: as a manager, I'll share my worries with the future of ongoing projects, the team, the organization. Mostly as preview of my current thought process that might translate to decisions/directives in the future, so when those decisions come in the future, there's no surprise.
- [ ] As a manager, I should be an enabler, not a bottleneck. In an ideal world, you don't have to wait for me to get things done. I want to invite you to anticipate future blockers by discussing ideas, expectations and work philosophy ahead of time, so you can comfortably make decisions that are aligned with the team when the time comes with confidence.
- [ ] Kaizen: constant improvement through continuous feedback. PDCA (Plan-Do-Control-Act).
- [ ] Past decisions are revised whenever we have new information.
- [ ] Quickies: I don't want to hear only good news.
- [ ] Quality is inseparable from work.
- [ ] Tests are critical and help engineering stay above water in the long run.

Some of which aren’t critical, and need to be timed correctly. If you have already been talking for weeks, or it’s someone you already have known previously, these are too introductory and should most likely be skipped.

- [ ] Meta 1-1: on how I filter out information before sharing. I will be as open as possible, sharing as much information as I can, except what won't make you more effective (e.g unclear/ambiguous/not-actionable information).

Versions

2022-10-31: initial list

Blogging Manifesto

2022-10-15T10:00:01+00:00

I’ve always been dissatisfied with blogging. The technologies bother the engineer-slash-idealist in me. I attribute the tedious publishing process as reason for not posting more often - although laziness is not out of question. In 2021, however, Obsidian.md came into my life and changed my perspective on personal notes, subsequently blogs.

The Ideal Blog

To set the scenario, here are my idealistic goals for a blog.

it is just files: it has to be simple. I don’t want to manage databases, adapters, migrations, seed files. Just good ol’ files.
I have full control: I want to control the design, the file structure, the domain, everything. With a just-files policy, I can move my site anywhere at any time. I learned a hard lesson with Evernote in the old days: migrating notes isn’t fun.
I write offline: writing should depend on internet. I want to go camping, be flying over the ocean, be in another country backpacking, and I want my ideas to come to life unencumbered.
writing is pleasing: what’s the point of writing offline but using Notepad? Some solutions feel good, but either require specific backends or internet. iA Writer feels amazing, but publishes to Wordpress, and I want none of that. Substack is ok but requires you to have the browser open and connected.
easy to publish: I should write somewhere offline, on a computer or on my phone, click a button and it goes online later.
quick iteration: I want to publish a not-totally-finished essay and improve over time. If publishing is one click, excellent. Copying/pasting is definitely no-go (looking at you, iA Writer).
it is (mostly) free: the idea of paying too much for hosting a few static files is obnoxious.
it is my 2nd-brain: I can take my tiny little notes, guides, and share with the world, not only essays.

I’ve gone through various technological iterations through the years, hitting a checkbox in one ideal but compromising another. Generally, solutions either (a) require too much technical knowledge to setup and maintain, like Jekyll requiring us to git checkout a directory in a terminal just to write posts, or (b) preclude content ownership, like in Wordpress - how are moving away from it if we change our minds in the future?

I’ve experimented through that pendulum more than I’d like to admit. From admin panels with Rails (full control, requires software engineering knowledge), Wordpress/Ghost/Substack (quick publishing, good for laypeople but makes changes difficult), to static pages on Netlify with Ember.js (for offline support), and lately Jekyll (plain files). But the whole list of ideals was never satisfied. Jekyll is supported by Github for free, but having to open a terminal to git-commit my markdown files is far from being a pleasure.

It sounds like splitting hair because, after all, it’s just… blogging, and the whole world has done it. However, concurrent to this analysis-paralysis in one area, on another I was actually thriving: I was writing a lot in Obsidian on my personal computer, it just happens to stay private. The more fundamental Obsidian became in my process, the more I realized that maybe, just maybe, if I could somehow combine blogging and Obsidian, publishing my notes into Jekyll hosted on Github, then maybe I might had solved all - or most of - those problems that bothered in the past.

Wait, but why Obsidian for note taking?

The concept of wikilinks are as old as 1995, but creating them had always been cumbersome. I think Roam Research was the first to introduce a simple User Experience for autocompleting wikilinks - in 2017. They enable you to create links between large and small notes in a very simple manner. Every time you type [[some note name]], it suggests other notes automatically, or creates new ones on demand. You end up with tons of notes connected.

Obsidian improved on Roam by making it pure markdown files on your computer. It means you can synchronize them across devices with whatever you want, from iCloud and Dropbox to rsync and git. You can also create your own code and iterate through your text. It’s open for extension, so you can use one of its hundreds of plugins.

If you like to take notes about books, for example, the generated visualizations are awe inspiring. To get a sense of how fun it is to have these notes connected, check the following two images. The first one shows a graph with all my notes and their connections (which doesn’t mean anything to you, but check the next one):

The usefulness of it is quickly zooming in and learning how multiple concepts connect together, remembering things I’ve written but had forgotten. It’s super fun and opens up a whole new mental level.

Obsidian deserves a post of its own.

When I started writing into Obsidian all my tiny little ideas in tiny little paragraphs, I had a sense that that should be my personal site (this text started as a note for organizing my own thoughts, and here it is now, public). However, my personal website was none of that. It’s hard to post anything so I will definitely avoid posting a couple paragraphs. The character-to-energy ratio is too low.

But I think I found a sensible way of keeping the simplicity of Jekyll with the offline support I’ve been looking for, by leveraging Obsidian’s plugin support. I now can click a button and post this note to Github in 3 seconds. Here’s how the ideal list stands:

✅ it is just files: it’s markdown, Obsidian and Jekyll. It’s a directory in my computer.
✅ I have full control: the site is on Github Pages and I control the design. It’s not Wordpress. Any sign of problem and I move somewhere, even a Raspberry Pi would do.
✅ I write offline: yes, and works on my mobile phone.
✅ writing is pleasing: I created a theme in Obsidian that mimics iA Writer’s. It’s a joy to write (although I miss Writer’s adjective checks).
✅ easy to publish: with the obsidian-github-publisher, it is.
✅ quick iteration: it’s a matter of pressing Cmd+Shift+D for deploying.
✅ it is (mostly) free: Github Pages is free.
🧪 it is my 2nd-brain: this is still in a discovery phase, but given I can publish any of my personal notes, I’ll say yes for this. I will have to improve my website layout for it to truly encompass all my notes.

The experimentation never ends, and I’ll definitely be improving the process as I go.

If you’re interested in setting up this combination with Jekyll and Obsidian, I’ve written a super technical guide on how to setup Obsidian for publishing on Github and Jekyll.

Jekyll Blogging with Obsidian

2022-10-15T10:00:00+00:00

I wrote about what would be ideal blogging process. I’ve always been dissatisfied with blogging due to how hard it is to post. When it is easy to post, then you generally lack freedom in some other fundamental area. I recommend reading that for context.

This post is about using Obsidian to send file to Github. It should work with any blogging framework, but given I use Jekyll, that’s what I’ll use here.

Ok, so how can I configure Jekyll and Obsidian together?

These are the instructions I’d need if I had to setup everything from scratch.

Step 0: have Jekyll in a repository. It’s outside the scope of this text teaching how to use it. It’s fairly simple if you know how to use it, but getting started can be tricky for non-developers. You can find tons of tutorials online, it’s a very basic blogging framework.

If you don’t use Jekyll, you can still publish to a directory in Github.

Step 1: write your notes in Obsidian.

The frontmatter of each file should look like the following. Frontmatter is really just a header for the file, and the --- indicate where it begins and ends.

---
share: true
title: "Jekyll Blogging with Obsidian"
date: 2022-10-15 06:00:00 -0400
filename: "guide/_posts/2022-10-15-jekyll-with-obsidian"
tags: [obsidian]
---

The actual article goes here.

where,

share: when true, it will push to Github (it is configured below in the plugin’s Settings screen)
filename: this is the place where your file will be saved in Github.
title, date, tags: these are standard Jekyll configurations and not critical here.

When you create a wikilink in Obsidian (an internal link), the publishing plugin will figure out the filename frontmatter value and replace links with those paths, translating to what Jekyll expects.

Step 2: install the obsidian-github-publisher plugin. This is a community plugin, so you’ll have to enable non-core plugins.

What it does is it sends files to a Github repository. For that to work, you need to configure a user, Github token, and the final file structure. These are described in the next step.

Step 3: time to configure the plugin. Go the plugin Settings (Cmd+comma on MacOS, then Community Plugins, then Github Publisher), you will find a list of properties to set.

The following are details about those properties.

Property	Comment
Repository	The plugin’s `README` has instructions on that. You’ll need a Github username, repo and token.
Folder Behavior	I set as `Fixed`. More details here.
Default Folder	I’m using `obsidian`. This puts all files published into the obsidian/ directory in Github.
Title Frontmatter	I’ve set mine to `filename`. This determines where the file will be sent to. For example, this post’s `filename: guide/_posts/2022-10-15-jekyll-with-obsidian` at the top, so the plugin will use it to figure out that it should move it to `obsidian/guide/_posts/2022-10-15-jekyll-with-obsidian.md`
Links	I turn on both `Internal Links` and `Wikilinks`. I want them to be processed.
Embed	`Transfer Attachment` should be on. For images, I set the Default Attachment Folder, I set `images/obsidian` (my Jekyll config expects `images/`).
Auto Clean	I think it makes sense to turn on `Auto Clean`.

Step 3b: the Text Replacer field is a bit more complicated. In short, it allows you to set some regex rules to rewrite some of the text during publishing.

Why would we want to rewrite the text? First, links need to match what Jekyll expects, so I set it to transform a wikilink like this

[[my-page|My Pages]]

to become the following in markdown,

[My Page](my-page)

However, Jekyll expects

[My Page]({% link my-page.md %})

Second, it appends obsidian to links, which the plugin wasn’t doing automatically (bug?).

In the Text Replacer section, each line has two fields. Let’s call the first entry and the second replacer. Here’s my configuration entries:

Rule 1, transform links ./: set entry to (?<!\`|\!)\[(.*?)\]$(?!(http|\/*image|obsidian\/image))(\.\/)*(.+?)(\.md)*$ and replacer to [$1]({% link obsidian/$4.md %}).

Why: this makes so wikilinks include the link function that Jekyll expects. If you are a little more technical and wants more details, here’s a commit I did with a nice ascii explanation.

Rule 2, adjusts image paths: set entry to (?<!\\`)\\[(.*?)\\]\$((obsidian\\/)?image)(.+)\$ and replacer to [$1](/image$4).

Why: image paths in Jekyll start at /images, but the plugin is converting it to /obsidian/images. This rule set removes /obsidian in those cases.

Finally, if you need to debug the conversion, search for the findAndReplaceText() function in Chrome’s dev console and add breakpoints to it.

Step 4: set a nice keyboard shortcut for publishing. I configured Cmd+Shift+Option+D for publishing only the open file, and Cmd+Shift+D for everything.

Is there `data.json` file I can copy?

Sure. Below is a copy of mine. If you want, paste into the plugin’s data file which lives in .obsidian/obsidian-mkdocs-publisher/data.json (in your Obsidian Vault directory). You have to replace the github keys and GhToken (as of version 4.4.0).

{
  "githubRepo": "blog",
  "githubName": "kurko",
  "GhToken": "ghp_[REDACTED]",
  "githubBranch": "main",
  "shareKey": "share",
  "ExcludedFolder": "",
  "fileMenu": true,
  "editorMenu": true,
  "downloadedFolder": "fixed",
  "folderDefaultName": "obsidian",
  "yamlFolderKey": "",
  "rootFolder": "",
  "workflowName": "",
  "embedImage": true,
  "defaultImageFolder": "images/obsidian",
  "autoCleanUp": true,
  "autoCleanUpExcluded": "",
  "folderNote": false,
  "convertWikiLinks": true,
  "convertForGithub": true,
  "subFolder": "",
  "embedNotes": false,
  "copyLink": false,
  "mainLink": "",
  "linkRemover": "",
  "hardBreak": false,
  "logNotice": false,
  "convertDataview": true,
  "useFrontmatterTitle": true,
  "censorText": [
    {
      "entry": "(?<!\\`)\\[(.*?)\\]\\((?!(http|\\/*image|obsidian\\/image))(\\.\\/)*(.+?)(\\.md)*\\)",
      "replace": "[$1]({% link obsidian/$4.md %})"
    },
    {
      "entry": "(?<!\\`)\\[(.*?)\\]\\(((obsidian\\/)?image)(.+)\\)",
      "replace": "[$1](/image$4)"
    }
  ],
  "inlineTags": false,
  "dataviewFields": [],
  "excludeDataviewValue": [],
  "metadataFileFields": [
    "obsidian"
  ],
  "frontmatterTitleKey": "filename",
  "shareExternalModified": false
}

Derisk

2022-03-13T19:00:00+00:00

If I had to point out one skill that differentiates great makers I worked with, it would be deliberate derisking. Everybody does it to some extent, but rarely as a constant discipline. It drives success and, once in motion, molds thinking and triggers valuable practices in all areas of life.

In short, you derisk by identifying future, expensive problems early on and finding ways to circumvent them. It is asking yourself, how could this go wrong? It’s asking yourself whether your wallet is in your pocket when you’re leaving the coffee shop, or getting reviews on your paper before you publish it. It’s thinking about knowns and unknowns before you invest your time.

Derisking is applied skepticism. You allow yourself to venture briefly into pessimism for short bursts of time so your brain has the environment and background to identify edge cases and think outside the box without analysis paralysis. In the process, it turns you into a realist and builds a healthy optimism. You and those around you being understanding in more depth the factors and the conditions that will drive your outcomes and decrease failures.

The process is somewhat straightforward and can be done mentally for everyday tasks depending on size. The decision on whether to mitigate a risk will depend on the risk-reward ratio. If the cost is too high, it might make sense to do nothing. On the other hand, if the cost of mitigation is too low, it probably makes sense to do it. Sending an email is low cost, but could have a high impact on the recipient. These are what we call asymmetric opportunities, inexpensive actions that can result in high rewards despite low risk.

To start simple, create a table with four columns: Risk, Probability, Impact and Mitigation. Each line is a risk. If you have a larger, high-stakes project, you will want to go into full details about each risk and their ramifications. If not, do it mentally.

Here are a few examples of derisking from different areas in life and their positive ramifications.

Risk leads to change in work cadence: long projects usually cause a divergence between what is expected by the customer and what is built. That is why architects build 3D models before construction, for aligning expectations on physical aspects and feelings (cozy? sober?).

Risk example: “Customer doesn’t find our solution useful”.
Probability: “High”.
Impact: “We lose trust and, subsequently, the deal”.
Mitigation: “Deliver in small matches so we get signals from the customer as soon as possible”.
This one is cheap to be done and can increase the customer’s trust. The Lean methodology was built around this problem, inspired by the scientific method which focuses on setting a small hypotheses and testing them so each step leads into the next.

The software industry suffered for decades with the so called “Waterfall planning”. It was meant to be like a house construction where you make a big plan upfront, document it, then develop it. The customer would only see the product once every detail was developed and implemented, often times with wrong requirements, a year or two later. In the 2000’s, a new manifesto was written proposing an iterative approach to decrease risks, by showing the software to the customer every day or every week.

Those small iterations reduce the risk of project dead ends.

Risk drives transparency: the risk of writing a 400-pages book and failing forces writers to get constant reviews and feedback of their drafts to make sure they’re going in the right direction. At work, the equivalent is getting feedback on plans constantly. That opens up the building process and everyone feels transparency, which helps with trust and aligning expectations early on.

In this new remote work world, I find it useful to say out loud the things I know most people are thinking about, topics such as anxiety about communications and expectations. It’s really to check in with people and hear their thoughts and identify what’s not transparent yet. This helps coworkers open up and support each other. This sense of transparency also helps leaders identify and anticipate problems before they have grown too much.

Risk example: “Code written is confusing for coworkers”.
Probability: “High” (most software code is painful to read).
Impact: “No one can change the software quickly later on, therefore the company suffers”.
Mitigation: “Create quick drafts of ideas and share with colleagues before work starts”.
Besides helping yourself with feedback, it shows your coworkers that you value and trust their opinions. It drives a culture of transparency and soon other people will be reaching out asking for feedback, making the organization more proactive. More transparency means less mistakes and bad decisions. That’s one of the reasons why top-down orders are usually frowned upon.

Risk drives personal rewards: people in different departments and on different level of the hierarchy care about different things. Micromanagement happens in part due to lack of clarity into what leaders really care about (and some due to trust issues). While you care about how to get your task done, your boss is probably thinking about how to make sure the customer is satisfied, or how failure on this and other 10 projects could impact their career negatively. They feel insecure that you won’t be upfront in case you see a risk or blocker that could result in lost customers.

The “solution”? Progress reports. Every month, every week, every day. This helps them at the cost of being seen as a stereotypical boss and the hidden cost of spending more time writing reports than delivering actual value to customers. A better solution? Invert the narrative, and show that you have interest in communicating your progress without them having to worry about it in the first place. It should help decrease micromanagement in most cases.

Risk example: “Not being recognized because my boss doesn’t know what I’m working on”.
Probability: “Low”.
Impact: “I could miss future promotions”.
Mitigation: “Write up status updates and blockers publicly twice a week for alignment”.
Your boss gave you the priorities for the week, but there’s are ramifications that they don’t have visibility into, including your thought process and the principles you’re applying. Although being Low risk, the cost of writing a paragraph is nearly zero and could help with that promotion the following year when you are seen as communicative.

Incentives, Perception and Expectations

For me, the most exciting part is derisking at the intersection of technology and people. I find useful to see it through the lenses of incentives, perceptions and expectations whenever trying to figure out elements that could hinder technical projects.

Everybody’s incentives are different. It drives their perception of reality, liking and disliking different things in different contexts and orders. That will always weigh on how your projects are ultimately judged. Your shiny project could fall short of people’s grace without alignment. Your boss is thinking about how that project will be factored into their goals and OKRs, after all that’s defining their bonus.

Here’s the critical problem is: everybody imagines and hypothetizes what everybody else’s incentives are instead of straight up talking about it. We think they’re aligned with ours, but they’re not. We forget that everybody had a different childhood history, different values and different principles. It’s not that derisking helps directly with that, but it forces you to understand the landscape in order to apply it.

There’s only one sustainable way forward: talking to them and practicing active listening. Some care more about quality than money, constant improvement rather than the work itself, self-image over actual work. Others just want to go home at the end of the day. You nurture a team by identifying their individual motivations and offering to participate in providing what they are looking for, never establishing rules and processes in a vacuum, without talking to the people and hearing what they have to say.

Derisk Early and Often

The earliest you derisk, the higher the chance of success. Any late derisking generally results in surprises - “why have you only thought about that now?” Finding out a pipe problem once the construction has been delivered is too late, or finding out the text you’ve written is not interesting after you publish is too late. The later we derisk, the more energy we need to steer the ship. Yet, we rarely focus on deliberate derisking, despite important projects in life. We are either too focused on the present, the quarter, a task at hand, and we forget to step back and reflect.

Derisking works alike in personal and work environments, and it’s mildly baked into our everyday life to the point we automate it. You look before you cross the street despite the semaphores. You check your tires before traveling despite the sensors being green. You check the destination’s weather despite it being summer. You set up Alexa to close windows automatically.

Now make it deliberate.

Software Complexity: Naming

2017-04-05T17:02:54+00:00

There are only two hard things in Computer Science: cache invalidation and naming things.

Phil Karlton

We all want to read and understand software. We want code to make sense, to speak the language of the business model, to convey meaning and relationships with clarity. Although code is written once, it is read many times.

Bad code confuses us. Bad code codifies assumptions that make sense for the writer but not for the readers. Have you ever needed help to understand a piece of code? Have you ever been demanded disproportionate energy and effort to make sense of what code was doing? That’s bad code.

But how do we go from bad to good?

The first step to succeed in any area is a solid understanding of its elements and their impact on other people and the environment. Good movie directors internalize elements and patterns after watching movies for countless hours, then manipulate them to tell stories effectively. The same can be said for novelists, musicians, chess players.

Similarly, a software developer should be able to scan a business domain and discover its elements and patterns. Some are obvious, some are not, and this is where it gets tricky: finding names for some of these elements is not a trivial task. Some elements don’t exist in the real world, some do but lack names everyone will understand. Some relationships are inevitable for the success of the business domain but were never discussed by the business owners.

Some names individualize elements whereas others aggregate them. Some reveal abstract symbols (graphs and nodes) whereas others make things concrete (cabled network and hubs). Some reveal roles (the administrators table), some reveal usage (users table), some reveal nature (people table). Some names don’t identify elements at the right level of precision (document vs XML), whereas some conflate multiple elements into one. Some just lack inspiration.

Good writing, as it turns out, is about optimizing for ease of reading.

Naming Components and Elements

There’s a whole universe of types of relationships among elements. Some things live side by side (e.g nodes), some contain others (organization vs employees). Some things depend on others (purchases and payments methods) while some generate others (bills and installments).

To uncover concepts and their names, we start out by asking simple questions, as if to prove that they make sense at all.

To illustrate our first concept, let’s start simple. Given the picture below, what room is this?

Question 1 of 3

Judging from this furniture, this is very likely to be a living room. Based on a component, we know the name of the room we’re in. That was easy. Next.

Question 2 of 3

Based on this object, we can fairly sure say that this is the restroom.

See a pattern here? The name of the room is a label that defines what is inside of it. With that label we don’t need to look inside the container to know what elements are there. That enables us to establish our first corollary:

Corollary 1: container name is a function of its elements.

Note it is basically Duck Typing. Does it have a bed? Then it’s probably a bedroom.

Now, the opposite is also true: based on the container name we can infer its components. If we were talking about a bedroom it would very likely that it had a bed. That enables us to define our second corollary:

Corollary 2: we can infer components based on the container name.

Pretty obvious, but now that we have some rules, let’s try to apply them to this next room.

Question 3 of 3

If our system is a house, a bed and a toilet in the same room makes the room definition, by all known western standards, pretty much blurry, foggy. Do you notice how using corollaries 1 and 2 becomes non-trivial to name this room? We could very well name it the Ambiguous Room.

In my experience, most of the time the challenge of naming things results from bad modeling. When the elements in software have been introduced without coherence, naming will be impossible. The developer, with short deadlines, are forced to deliver whatever comes to mind first.

At home, we put together things that have the same function, purpose and intent. That makes organizing easier, whereas by messing with these responsibilities we cannot be sure what the architects wanted or how these objects are meant to be used, blocking flow.

Corollary 3: the clarity with which a container is defined is proportional to how closely related its components are.

This is hard to read, so let’s use a picture:

When components are related, it’s easier to find a good name. When things are unrelated, it becomes increasingly difficult. The word relation here could be their functionality, their purpose, their strategy, their type, and others. Relation on its own doesn’t mean much until we talk about criteria. Bear with me here, and we’ll get to that soon.

Note that these assumptions would flip upside down if our system was a prison, not a house. In that case, the reader would easily identify this room as a prison cell. That leads us to an important definition.

Corollary 4: a container definition is constrained to its context.

This seems obvious when our focus is on the definition of the container, but this surfaces another problem: it is common for systems to leave context undefined. A module represents context, and submodules represent sub-contexts.

When most code is flat, the context definition is missing, preventing differentiation among containers. The cues that indicate that where code should go don’t exist, and so it feels like code is random.

For example, a directory without any modular segregation, with flat classes serving all types of functions, from database manipulation to authentication, custom data structures and view logic, will hide contexts and prevent cues from emerging, resulting in inferior readability.

This creates incentives for developers to add code anywhere because there are no hierarchical cues. As Alan Kay puts it,

Most software today is very much like an Egyptian pyramid with millions of bricks piled on top of each other, with no structural integrity, but just done by brute force and thousands of slaves.

Example 1: HTTP domain and a car

HTTP is a domain and it has requests and responses. If we were to put a component called Car within it, we wouldn’t be able to call it HTTP anymore. In this case, it becomes something confusing.

public interface WhatIsAGoodNameForThis {
	
	/* methods for a car */
	public void gas();
	public void brake();

	/* methods for an HTTP client */
	public Response makeGetRequest(String param);	
}

Example 2: Coupling through words

A common pattern is appending Builder and other Er-ending words in class names. SomethingBuilder. UserBuilder, AccountBuilder, AccountCreator, UserHelper, JobPerformer.

Judging by the name, we can interpret three things. First, the verb Build in the class name implies that it’s a function, when in fact it’s in the class title. Functions do stuff, classes embody entities and context. A function is not an entity, and without entities well defined the codebase quickly develops into procedural code because it’s sub-utilizing the class pattern’s original intention.

Second, it has two inner, hidden entities within it, a User and a Builder, meaning a probable encapsulation violation. By that we mean that a User shouldn’t be responsible for generating new Users.

Third, it implies that Builder has access to how a User functions internally because, after all, they’re entangled with one another.

I’ve seen entire codebases littered with this approach. There are complicated patterns that attempt to solve this, like FactoryPattern. Some times they’re useful, but when we have a modeling problem, we better fix it, not bandaid it.

Example 3: Base

Let’s look at a few real life examples. First one, the I18n Ruby gem (only class and method names provided for brevity):

class Base
  def config
  def translate
  def locale_available?(locale)
  def transliterate
end

Here, Base doesn’t express meaning. It can configure and translate, as well as figure out whether a locale is available or not. It’s doing a few different, unrelated things.

Example 4: names guiding design

When we talk about how names can guide our design, Discourse has a few examples, one of which interests us.

class PostAlerter
  def notify_post_users
  def notify_group_summary
  def notify_non_pm_users
  def create_notification
  def unread_posts
  def unread_count
  def group_stats
end

The name PostAlerter suggests functionalities that alert someone about a post. However, unread_posts, unread_count and group_stats clearly deal with something else, making this class name not ideal for what it does. Moving those three methods to a class called PostsStatistics would make matters clearer and more predictable for newcomers.

class PostAlerter
  def notify_post_users
  def notify_group_summary
  def notify_non_pm_users
  def create_notification
end

class PostsStatistics
  def unread_posts
  def unread_count
  def group_stats
end

Example 5: ambiguous names

The Spring framework has a few examples that illustrate components that do too much and, as a result, require names that resemble our Ambiguous Room. Here is one (because this one would be just a bit too much):

class SimpleBeanFactoryAwareAspectInstanceFactory {
  public ClassLoader getAspectClassLoader()
  public Object getAspectInstance()
  public int getOrder() 
  public void setAspectBeanName(String aspectBeanName) 
  public void setBeanFactory(BeanFactory beanFactory)
} 

Example 6: good naming, for a change

Enough of bad naming. Good naming can be found in D3’s arc, for instance:

export default function() {
  /* ... */
  arc.centroid     = function() { /* ... */ }
  arc.innerRadius  = function() { /* ... */ }
  arc.outerRadius  = function() { /* ... */ }
  arc.cornerRadius = function() { /* ... */ }
  arc.padRadius    = function() { /* ... */ }
  arc.startAngle   = function() { /* ... */ }
  arc.endAngle     = function() { /* ... */ }
  arc.padAngle     = function() { /* ... */ }
  return arc;
}

Each one of these methods make total sense: they are all named after what an arc has. And what I love about the image below is how simple it is.

Method 1: Break Apart

When to use: you cannot find a good name for a class or component, but you already have isolated concepts and want to find good names for their groupings.

It consists in two steps:

identify the concepts we have
break them apart

In the toilet + bed scenario, we pull apart each different thing we can identify by pushing bed to the left, toilet to the right. Ok, now we have two separate things that we can finally reason about in a natural way.

When you cannot find a good name for something, you probably have more than one thing in front of you. And, as you know by now, naming multiple things is hard. When in trouble, try to identify what pieces and actions compose what you have.

Example

We have an unnamed class containing a request, response, headers, URLs, body, caching and timeout. Pulling all those apart from this main class, we’re left with the components Request, Response, Headers, URLs, ResponseBody, Cache, Timeout and so on. If all we had was the name of these classes, we could fairly sure assume we were dealing with a web request. A good candidate for a web request component is HTTPClient.

When the code is hard, don’t think about the whole first. Don’t. Think about the parts.

Method 2: Discover New Concepts

When to apply: when a class is not simple or coherent.

Discovering new concepts requires knowledge of the business domain. When software applies the same nomenclatures as the business, an ubiquitous language is established (Evans, 2003), one that allows professionals from different areas of expertise to speak the same idioms.

Example 1: encapsulating components into one new concept

A few years ago, a company was about to lose a big contract. Why? Because the team was slow to ship new features and fix bugs.

This marketplace ecommerce charged students with different rules in different countries with multiple payment gateways. Requirements were fairly complex. When I saw the charge code, PaymentGateway, I was shocked at how complicated it was, with several dependencies, including: User, UserAddress, CreditCard, BillingAddress, SellerAddress, LineItems, Discounts, and more. Its constructor was gigantic and this complexity made it hard to add new rules, as touching one thing broke others, as well as requiring us to change all gateway adapters.

The problem extended beyond payments. Emails were sent to students by having messaging classes aggregating all this data again. Technical support had their own screens with this data aggregated a third time, except that this particular place was using a class called Aggregator (word that means nothing without context). We had to do something to fix this architectural blocker.

To solve the problem, I started with a mind exercise. Here’s an idea of how it went:

Here I am, with these details about things I need you (the PaymentGateway) to charge for me. If this was a desk, I’d have these papers organized and I’d probably call them Invoices. So what if I created one class called Invoice, which is nothing more than the aggregation of all these other details, such that the gateway doesn’t need to know how those rules are done because Invoice will? Instead of injecting a million objects, I just hand one over to you?

The Invoice term wasn’t used anywhere. We spent a month refactoring on the side and once we were done, we were able to change the software much more swiftly.

Invoice is a good example of concept that is but an aggregation of data from many sources and the majority knows what it is. The final solution added the Invoice class which alone was injected into the gateways, serving as a facade pattern and hiding other classes.

Good naming is not just about writing beautiful words, but also writing precisely what needs to be expressed that wasn’t before.

Example 2: Pivoting names based on the business domain

In a greenfield, carpooling project, we designed the system from the ground up and during research with other transportation solutions, the appropriate word to describe someone’s journey on a given day from origin to destination was trip, and the group of people was called ride. We published a glossary so the rest of the company could discuss and share the same ubiquitous language.

After launch, our customers always referred to trips as rides. Soon we had problems translating support requests to what had to be done, and after some considerable pain, we decided it was time to refactor trips to rides and rides to carpools. That solved the problems of one company speaking two different languages.

Example 3: levels of abstraction

One person says, move right leg then left leg then right leg, other says walk. Both mean the same, but the latter is said to be more abstract.

Ideally, as the code gets closer to its public API, the closer it tries to match business nomenclatures. As it get close to the database and to the metals, it uses machine nomenclatures that relate to its context. In between, a gradient that goes from more to less abstract.

In one company, a business person would say post Tweet, so a name such as postTweet() would make more sense in a public API than makeHttpRequest(). In a company with a more technical service, the latter would be more adequate.

Second, consider specificity. postTweet() is very specific, whereas makeHttpRequest() is so generic it could be used for Facebook or basically anything involving HTTP. A generic name can be reused easily on the price of being vague. That explains why frameworks code are so different from business software code.

Example 4: generalization

A long ago, a CMS had database tables news, history, videos, articles, pages and other. Most of them had the same columns, title, summary and text. The videos table had extra attributes such as url (to embed YouTube) and history had a date attribute so the page would show a list of historic events by year. All these tables looked like copies, with a few differences here and there, and adding new functionality required rewriting a lot of boilerplate all over again.

I collapsed all those tables into one called contents with a foreign key pointing to a table called sections, which had the list of sections such as news, history, videos and others. Now, one code for contents was enough. Years later, a friend had to write a small CMS and I suggested the same approach. Once the forms for managing content were done, it took 1/N of the time it would normally take to implement anything because for every new section of the same type, it was already done.

Generalizing by giving it another name enables great productivity. News is a Content. Article is a Content. History is a Content. Can all of these share the same attributes? Yes. Survey? No, not a Content.

Method 3: Criteria For Grouping

When to use: when names are good but they don’t fit well with each other.

Components can be grouped by a variety of criteria, including physical nature, economic, emotional, social and, the most used in software, functional. Photo frames are grouped based on emotional aspects, whereas products are grouped based on economic motives. Couch and TV stay in the same room, grouped together based on a functional criteria, as they both have the same function or purpose, to provide leisure.

In software, we tend to group components by function. List your project files and you will probably see something like controllers/, models/, adapters/, templates/ and so on. However, some times these groups will not feel comfortable and that will be the perfect time to reevaluate the structure of your modules.

Example: grouping by strategy

A library for automating documentation operations generates a spec file (i.e API Blueprint) based on code, lints said file (to guarantee is correctly formatted) and uploads to the cloud (i.e S3).

Based on the document format, a variety of subsequent decisions will be made automatically. Choosing API Blueprint will pick up a different linter, a different tester and a different API Elements converter. The key word here to group all of these different functionalities based on one input is strategy. Following that, the library includes a module (or namespace) called Strategy to group together file formats, linters, document testers and storage providers. That enabled the library to separate ordinary operation files like uploaders, parsers and command-line from business core strategies.

Leveraging Contexts

Every app has a different context, and every module within it, every class within them, down to every function. The word User alone could mean user of the system, but also perhaps a database table, or a 3rd-party service credential. lib/billing/user differs from lib/booking/user, but they’re still user.

Imagine that every container, such as a module, is a bucket. Within them, components are insulated from the outer world. You’re free to name those classes whatever you want. It frees the mind from having to find esoteric names for common things.

One strong argument for microservices (many, isolated buckets) over monolithic architectures (one big bucket with small buckets within) is that it enforces constraining responsibilities within each service because now you then cannot easily entangle completely unrelated things with each other. Billing lives inside BillingApp, booking inside BookingApp and so on. In a monolithic architecture, these respective service names could be simple module names, but not everyone has the discipline to keep things tidy.

Example: Namespaces

Mark is building an ad platform that needs to generate hundreds of thousands of ads, then send it to AdWords, Facebook and Bing, all managed through a Graphical User Interface.

Mark starts with an entity called Ad which soon gets bloated. AdWords’ ads have headline_part1 and headline_part2, Facebook’s don’t, while Bing has only headline. He needs to think of a way to split his entity. He ponders about the different contexts and how he could leverage the language’s namespaces feature to express that. He comes up with the following structure:

Adwords::Ad: this represents an ad object in Adwords. It has attributes that are unique to Adwords and the logic can be contained in this class.
Facebook::Ad: same as the previous one, except that it has Facebook’s specific requirements and logic.
Bing::Ad: same as above.
RemoteAdService::Ad: this serves as an interface between Adwords::Ad, Facebook::Ad, Bing::Ad and the rest of the system. This means that these three class will all have the same public API, allowing the system to leverage polymorphism.
Database::Ad: this is the ORM for the ads table. It uses ActiveRecord, DataMapper or any custom solution.
GUI::Ad: this represents the attributes required for display of an ad in the UI. It possibly has presentation and internationalization functionality.
API::Ad: an HTTP endpoint for an ad will have its own custom attributes, therefore it makes sense that the serialization logic lives here.

Words can mean different things depending on context, and when we leverage context, we can choose simpler words for components. In this example, we didn’t have to do any acrobatic movements to find those component names because they’re all one thing, ad.

Meaninglessness and neologisms

Over the years, names evolve and acquire news meanings. Others come in to fill in holes.

Helper: helpers are functions that support the main goal of application. But then, what’s the criteria to define what’s the main goal of the application? Everything in an application supports the main goal of an application.

In practice, they’re lumped together in an unnatural grouping to provide reusability for some miscellaneous, commonly used operation. They tend to suffer from Feature Envy, where they need to access another component’s internal data to work. They’re an excuse for things that one can’t find a proper name.

Base: classes named Base were a convention a long time ago in C# to designate inheritance when lacking a better name. For example, the parent class of Automobile and Bicycle would be Base instead of Vehicle. In spite of Microsoft’s recommendations to avoid that name (Cwalina, 2009), it infected the Ruby world, most notable via ActiveRecord. To this day we still see Base as a class name for something that developers cannot find a name for.

Variations of Base include Common and Utils. The JSON Ruby gem Common class has the methods parse, generate, load and jj, for instance, but what does common really mean here?

Tasks: there is a wave in the Javascript community to call asynchronous functions, tasks. It started with task.js, and the term became used even when that original library wasn’t present.

Does everyone in the team understand it? Then it’s fine! But what about when someone new joins the team and nomenclature that exist since the 60’s are thrown into garbage?

I worked in a project where the name of a class was, guess it, Atlanta. Yes, Atlanta. Fucking Atlanta. No one knew or could tell me why that was called that way.

Communicating

“Reality exists in the human mind and nowhere else.” George Orwell

I believe the practice to excel at communication to be an act of altruism, and the effort we put into improving our skills is correlate to how much we care about other people. We want people to understand easily, we want to remove the friction and barriers.

Secondarily, we want others to understand us. By accepting that a Receiver getting a message is a Sender’s responsibility, we build an empathic environment. It’s a win-win situation. There are no excuses for not deliberately practicing our communication skills - unless you live in the jungle.

With writing, we optimize for reading and the exercise in empathy can be exhausting. But, as everything in life, proficiency only comes to those who practice.

Bibliography

Cwalina, Krzysztof. 2009. Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, Second Edition. Boston: Pearson Education, Inc. 206.

Evans, Eric. 2003. Domain-Driven Design: Tackling Complexity in the Heart of Software. Boston: Addison-Wesley Professional.

A Fractal of Black Boxes

2016-11-24T17:02:54+00:00

Most software today is very much like an Egyptian pyramid with millions of bricks piled on top of each other, with no structural integrity, but just done by brute force and thousands of slaves - Alan Kay

I am perplexed about the sudden and continuous development of civilization, given the absurdly high complexity permeating our everyday lives. Yet, we rarely notice how complicated everything is. Consider for a minute: when driving, your foot is influencing thousands of explosions per minute. Or when clicking the volume button in your TV remote, millions of electronic instructions are taking place. Endless iterations have gone by in centuries around the world to bring us the stoves in our kitchens, yet heating milk looks mundaine.

Or, yet, you board an airplane, sit comfortably, and arrive a few hours later on the other side of a sphere floating around a burning star. How many million hours of work have gone into developing something that is heavier than air and faster than sound. That is out of sight and our brain is looking for the button to recline the seat to enjoy a movie.

We experience simplicity because we only look at the surface in front of us. Beneath, however, are layers and layers of gradual and hierarchical complexity. The hood, the components, the engine, the mechanisms inside, the spark plug, the camshaft, and the descent into physics and chemistry. It’s fractals of black boxes all the way down.

The good news is that we can use the principle of progressive compartment to manage most complexity, making maintenance and innovation simpler in many areas of life. These black boxes reduce the need to think about what is out of sight until we have to. What we experience is gradual layering. Like russian dolls.

In education, one starts with the foundations, then moves on to harder topics. First you learn to read, then you learn to write. In real state, first you research by geography and price, then you move on to the specifics. In software, you don’t put the what and the how in the same level. In a book, you first have the index, then the chapters, then concepts laid out gradually in paragraphs.

This is the art of making complex things simple and hard things easy. Flat hierarchy tends to produce more complexity, but compartments help contain entropy.

Tiny Tiny Machines

Biology inspired engineers to think about components as cells, or objects. When engineers at Xerox PARC in 60’s and 70’s envisioned an electronic board as composed of interdependent, tiny little machines communicating among themselves, it opened a door into a future that incredibly vast (but in great part is still waiting to happen).

The greatest system to have flourished from this framework is the Internet itself. Peers anywhere on the planet are able to send and receive messages through millions of network nodes. This cell-like architecture enabled the countless revolutions we have experienced.

The cell membrane separates and protects its interior from the environment. The many different types of specialized cells cooperate with each other by passing materials around. Alan Kay argued that applying these concepts to human-made systems, making objects bounded by these characteristics, “messaging, local retention and protection and hiding of state”, would yield better and more robust systems.

Object orientation is a mental model about the world. It segregates components and hides their complexity by abstracting away their internals, like small black boxes. Information about the system is compacted, and the brain can scale reasoning step by step. It is a recipe for simplifying all areas of life, from your to-do app (with areas and projects and tasks and subtasks) to banks, from real state to engineering.

Software

At the root, object orientation had no relation to programming languages. It was always about the messages components exchange. Whatever the paradigm, the value is in managing the application’s state and structures in a way that is self-contained.

Classes, inheritance, mutability versus immutability, came to be associated with it decades later, with C++ and later Java. The debate, object orientation versus functional languages, has always been moot because you can have boundaries in any paradigm. When asked what languages could apply it, Alan Kay’s replied, “Lisp”.

Take Erlang, a functional language. Each BEAM process is a functional program getting a stream of messages. Outside a particular process there could be all sorts of chaotic occurrences, a storm raging, but we do not care. The compartmentalization lets us focus on what individual components need to do and only that.

In 1969, Smalltalk was born as a project to create a programming language based on these principles. C++ (1983) and Java (1995) are the most famous, although not the most representative. When asked about C++, Kay replied, “actually I made up the term object-oriented, and I can tell you I did not have C++ in mind”.

Curiosity Mars Rover

Curiosity Mars Rover is a great example of system built with object orientation in mind. Written in C, it applies the concepts information hiding and boundaries to contain its complexity.

Curiosity has over 2.5 millions lines of code. Composed of many modules, they use a message queue written specially for the rover. Whenever a module needs an information or something to be done, messages go into the queue, which will dispatch it to the target module, which will then execute what’s needed. There are no mutexes, no transactional memory.

If a message is a command, module A never expects an answer or return value from the receiving module B because they are independent. If module B breaks or goes offline, module A is never impacted by it. If it’s a query message, then a return value is expected but no state can be changed.

Besides the evident robustness, this decouples module A from module B. There are no setters. When working on a module, you are not required to know how another module works. Cognitive load is lower. Different teams can comply with a contract of how the interfaces are designed and work in parallel. Debugging gets easier because you can apply binary search to figure out which modules are the root cause.

Changing the system is easier due decoupling, provided changing one part of the system won’t require you to change anything else. Like in Erlang, processes are deployed to production independently while other components continue running. From another angle, NASA basically rewrote Erlang in C. And as Joe Armstrong once jokingly said,

Erlang might be the only object oriented language.

A Fractal of Perspectives

The principle of black boxes can be applied to distributed systems, microservices, text codebases, and even Unix pipes. In code, we tend to use namespaces to convey components, hide states from other components and see methods as representations of messages.

All systems have some coupling, some level of complexity and an unescapable cognitive burden. It’s our responsibility, however, to manage it.

Physics of Software

2014-08-19T17:02:54+00:00

Update (2015): A year after publishing this article, Adrian Bejan, who discovered the Constructal Law, invited me to speak at the Constructal Law & Second Law Conference at the University of Parma, Italy. No one had connected it with software yet. Presenting was... interesting. Presentations were the academic precision of a jet engine, whereas I came prepared with memes, like a proper tech talk. It was an honor to present how his physics principle applies to software architecture to an interdisciplinary audience. Scary, but cool.

Look! Look! Look deep into nature and you will understand everything.
—Albert Einstein

Some time in 2013, I picked up a book that connected several dots in my understanding about reality. I had always wondered why rivers resembled city layouts, or why lungs and snowflakes had similar formats, or trees and lightnings look so alike. I had no idea that Design in Nature: How the Constructal Law Governs Evolution in Biology, Physics, Technology, and Social Organization would help me reason and design better software.

I does feel off reading nature and design in the same sentence without a hint of religion or mythology. After all, everything resulted from random, stochastic processes. Rivers, mountains and vulcanoes had to compete for space, expanding, contracting, flowing, pressuring and many other verbs throughout millennia. How come design played any role?

Well, what Adrian Bejan figured out is that the processes are as random as we think. The fundamental law underneath the battle of the elements connects disparate manifestations and discovers what drives their shapes,

For a finite-size system to persist in time (to live), it must evolve in such a way that it provides easier access to the imposed (global) currents that flow through it.

Constructal law

Putting 2 and 2 together, whenever something needs to flow from point A to point B, the tree-shape arises.

The designs that happen spontaneously in nature reflect this tendency: they allow entities or things to flow more easily – to measurably move more current farther and faster per unit of useful energy consumed. Even streets and roads, despite being artificial constructs, tend share this pattern for maximum mobility.

Order and disorder

Software designers win by separating things that can be considered separately, lose by separating things that must be considered together. - Kent Beck

In a long enough timeline, software development feels like a semi-random evolution. Real-world concepts compete for space in the codebase by means of classes and names, expanding their meaning, contracting when they get confusing, flowing through polymorphism or pure classes, pressuring when it blocks us from making further changes.

Every team breaks bloated components into smaller, isolated pieces. It helps them identify those pieces quicker and maintain them. But over time, as the push and pull continues, different teams collaborate and oppressive deadlines force abrupt, unplanned changes, those pieces start to drift and lack cohesion, sometimes being duplicated or just not making sense anymore in the grand scheme of things.

Neil Johnson said it better,

The [complex] system appears to be “alive”. The system evolves in a highly non-trivial and often complicated way, driven by an ecology of agents who interact and adapt under the influence of feedback.

Complexity must grow. Thread by thread, it creeps in until the simple is knotted.

For example, consider complexity as the number of interactions between components. With 2 components, complexity is 1, half its size.

What happens if we add an extra component? Complexity jumps to 3!

We hit complexity 15 when reaching mere 6 components, a staggering growth This exponential growth is staggering.

This is an extreme case for the sake of the argument, but fair enough topology to express how complexity grows untamed. Such extreme examples are not uncommon, though, as every software team knows well.

Applying the Constructal Law to tame disorder

Having in mind what we know about Constructal Law, we can redesign the architecture, minimizing the flow pathways to contain complexity.

Above, we increased the system size by adding a 7th object, while decreasing direct flow from 15 down to 8. In practice, that is achieved by patterns like Facade or Gateway (single entry to subsystem), a Mediator (central coordinator), Application services (one orchestrator per workflow), or a command or event bus, to name a few. Each replaces a many-to-many mesh with a star (hub) or a pipeline.

Modularization isolates subsystems, as long as the entrypoints are designed intentionally. By moving away from a flat architectures, scarce, well-defined entrypoints will support sustainable growth.

On the other hand, here’s how to take the first step to mess up your subsystems.

Why is this so bad? Well, whenever we must change B, we’re forced to change A too. Every change becomes larger. Second, once you broke a boundary, it’s inevitable that these violations will continue into the future.

Overall, ensure less interactions between deeper components, if possible. Create facade objects that delegate the flow further downstream. Although breaking them in smaller pieces is a great first step, but it is preventing whatever components from talking to whatever other components in another subsystem without intentionality that will make sure your overall system remains simple.

Alex Oliveira

Code agents in 2026

Patterns

Start a flywheel effect

Skills: Recipes as prompt

Subagents: Fighting context rot

Parallelism

Five Days on the Kumano Kodo

A total reset

Day 1: Takijiri-oji to Chikatsuyu

Day 2: Hosshinmon-oji to Hongu

Portals

Day 3: resting in Yunomine

Day 4: Kogumotori-goe to Koguchi

Shipping weight

Back on trail

A new friend

The peak

Koguchi

Bear spray disposal

Day 5: Shingu to Nachisan

Tomorrow

Planning a walk in Japan

A good walk

The shape of the walk

What would be the ideal trail?

Planning takes a hit

A new partner

The ground shakes

The Nakahechi trail

T-44 days to hike

Logding

Elevation Reckoning

Exercise shock

How much trouble am I in?

Travel starts

A lost week

San Jose: back to square one

The last mile

Tokyo to Kyoto to Tanabe

Problem-solving template

Why would we use such a template?

The template

My universal coding prompt (Claude Code, Cursor and others)

What’s behind this prompt?

How does it align with prompting best practices?

The prompt

The Space Between Yes and No

What does bang methods mean in Ruby?

Remove Distractions From Websites

Ok, so how do I do it?

Visto Japonês como Brasileiro

A Reserva de Passagens com PNR

Meditation

Generate CSV from Rails console (Heroku)

Method One: Pipe Into a File

Method Two: With Slack

Roadmap for One-on-One’s

The List

Versions

Blogging Manifesto

The Ideal Blog

Wait, but why Obsidian for note taking?

Jekyll Blogging with Obsidian

Ok, so how can I configure Jekyll and Obsidian together?

Is there data.json file I can copy?

Derisk

Incentives, Perception and Expectations

Derisk Early and Often

Software Complexity: Naming

Naming Components and Elements

Method 1: Break Apart

Method 2: Discover New Concepts

Method 3: Criteria For Grouping

Leveraging Contexts

Meaninglessness and neologisms

Communicating

A Fractal of Black Boxes

Tiny Tiny Machines

Software

Is there `data.json` file I can copy?