I'd glanced at agent prompts before but never stopped to deeply interrogate one. After a frustrating session with a subagent test writer, I hit Ctrl+o and read the prompt it was given. There it was. Clear as day. Claude was working against my own well-developed skills, strongly conflicting with my preferences. Annoying.

My skill library is extensive. On top of that I have agents that use those skills and coordinate with each other. The problem wasn't the library or the agents. It was the hand-off. The primary agent, the orchestrator, was providing too much context when spinning up subagents, and that context was working against the skills and directives I'd carefully built.

These skills capture behavioural- as well as task-oriented perspectives. They understand personas, software flows, even user stories. The orchestrator wasn’t accounting for that. My library subagents already know the how, they just need to be told the what so they can get started.

With a mature skill library, the orchestrator’s job needs to evolve in a specific way alongside it. Especially as you begin encoding task-specific instructions in skills and subagents, it needs to defer rather than deeply instruct. Currently I’m solving for that deferral with a dedicated agent-briefing skill. This lets the primary agent orchestrate a clean hand-off without on-the-fly re-inventing my skill library.

Subscribe now

How mature is your agent/skill library? If you’re consistently handing off to subagents, scrutinizing the orchestrator’s prompt is worthwhile. You might find its prompting is undermining your expectations, generating output counter to your own skill library. Annoying.

1. No library: the primary agent (Claude, Gemini, etc) improvises everything with behavioral and task context both living in the prompt. This is fragile and inconsistent.

2. Emerging agent library: subagents exist but skills are thin. Context is buried inside agent instruction files, invisible by default. Iteration is blind.

3. Mature library: behavioral context lives in skills, agents, and a well-curated primary instruction file. The primary agent passes only task context. Invocation prompts get shorter as the library gets better.

This isn't a strict progression. If you know the shape of the library you’re building toward you can skip ahead (hint: start working on skills). At stage three the primary agent gets out of its own way. Then subagents start performing much closer to how you actually expect.

Subscribe now

Here’s a Claude Code example you can drop in. The shape transfers to other agents with glob-based permissions, though the syntax varies.

Subscribe now

{
  "permissions": {
    "deny": [
      "Read(**/.env*)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(**/master.key)",
      "Read(**/*.yml.enc)",
      "Read(**/secrets/**)",
      "Read(**/credentials/**)",
      "Read(**/*token*)",
      "Read(**/node_modules/**)",
      "Read(**/dist/**)",
      "Read(**/build/**)",
      "Read(**/_build/**)",
      "Read(**/deps/**)",
      "Read(**/vendor/bundle/**)",
      "Read(**/ios/Pods/**)",
      "Read(**/android/.gradle/**)",
      "Read(**/log/**)",
      "Read(**/tmp/**)",
      "Read(**/coverage/**)",
      "Read(**/*.min.js)",
      "Read(**/*.min.css)",
      "Read(**/*.bundle.js)",
      "Read(**/*.map)",
      "Read(**/*.sqlite3)",
      "Read(**/*.db)",
      "Read(**/*.log)",
      "Read(**/*.apk)",
      "Read(**/*.ipa)",
      "Read(**/*.aab)",
      "Read(**/*.pdf)",
      "Read(**/*.png)",
      "Read(**/*.jpg)",
      "Read(**/*.mp4)",
      "Read(**/package-lock.json)",
      "Read(**/yarn.lock)",
      "Read(**/Gemfile.lock)"
    ]
  }
}

To prevent this repetitive cycle and cut down on token usage, I built a “cartographer” agent. Its only responsibility is to “chart” a codebase by crawling it to produce a markdown document specifying purpose, architecture, the data layer, entry points, and conventions to name a handful. The output of this agent, while helpful for humans, is not for humans. This is a new class of files I track in repos specifically for agents.

The cartographer is specific in how it runs. It's an agent, not a skill, because we don't care about its run-time context; a distinction worth knowing to get the most out of agents. We only care about its output. It's important, too, that the “chart” it produces strikes a balance between orienting agents and surviving change. The right ceiling is directory-level: capture what components own, not what each file does. Go deeper and this file churns on every PR. That's an upkeep nightmare.

Here’s an example, lightly scrubbed, taken from a real project:

**Per-tenant GenServer architecture:** The central design decision: every active tenant runs exactly one Worker GenServer. Workers are named via a Registry keyed on tenant name, so routing an incoming event requires only a GenServer.cast to the registry-registered name. There is no database lookup on the hot path.

**Supervision tree:**
- Monitoring.Supervisor: DynamicSupervisor that owns all Worker processes
- Monitoring.Manager: loads active tenants from the database on startup and starts a Worker for each; handles runtime worker lifecycle
- Monitoring.Worker: per-tenant GenServer; traps exits to persist state on shutdown
- Monitoring.Counter: pure functions for sliding-window counter math; no process, no side effects

**Outbound Dispatcher:** A single GenServer that receives fire-and-forget casts from Workers. Keeps HTTP I/O off the Worker call path.

**Context boundary:** A Phoenix context module provides the only public API into the persistence layer. Controllers and GenServers go through it; nothing touches Repo directly.

Two additions make this agent especially helpful. First, a directive in the agent’s instruction file (i.e., CLAUDE.md) to read this document before starting work. By doing this, the agent immediately grounds itself in the structure and conventions of the project. No more globbing. Second, other agents know to run the cartographer when significant work wraps up, keeping the chart current without manual upkeep.

Subscribe now

The teams getting the most out of agents aren’t the ones with the cleverest prompts. Instead, they’re the ones who’ve made their codebase legible for agents, the same way good teams always have for humans.

The frontmatter of a skill file is what the agent keeps in context. It’s how the agent knows what skills are available. The rest of the skill isn’t loaded until it’s decided the skill is needed. After working with skills for a bit, my own descriptions evolved into something like this:

Applies commit message standards for scope, title format, and body content. Use when creating a git commit, staging files, writing the message, or deciding when work is ready to commit.

That’s a start. The best part is the second sentence, “Use when…” That gives the agent the strongest signal. The prose before that reads more like it’s for us the humans. “Use when…” is the germ of the idea. Let’s build on that by pulling in bullets and strengthening the examples for the agent:

---
name: commit-helper
description: |-
  Use when the user:
  - Asks to create, write, or record a git commit ("commit this", "let's commit", "make a commit")
  - Says the work is done and ready to commit
  - Wants help writing or improving a commit message title or body
  - Shares a diff or set of changes and needs a commit message written for them
  - Asks whether staged changes are ready to commit or if the scope is right
  - Mentions staging files before committing ("git add", "stage these", "what should I stage")
  - Wants to know why a commit message is bad or how to fix it
  - Asks about commit message conventions, format, or style

  Do not use when the user:
  - Wants to push to a remote, open a pull request, or create a PR
  - Asks about git history, log, or past commits
  - Wants to amend, rebase, or revert an existing commit
  - Asks about branching or merging
---

An accompanying prose description would be useless. Instead, with bullets setting off the Use when and Do not use when, you can concretely demonstrate when the skill needs to fire.

Subscribe now

This final part is for your agent 🤖

Writing Skill Descriptions for Agent Routing

Use the |- YAML block scalar. This preserves newlines so bullets render correctly in context.

Do not open with a prose summary. Drop straight into Use when the user:. A sentence describing what the skill does before the bullets is redundant. The bullets carry that meaning while also doing the routing work.

Structure:

description: |-
  Use when the user:
  - ...

  Do not use when the user:
  - ...

Bullet quality

• Target at least 6 bullets in Use when

• Each bullet must introduce genuinely distinct vocabulary or context. “Save this link”, “keep this link”, “store this link” is one bullet, not three

• Include specific example phrases in quotes where they help matching

• Frame every bullet as a user action, starting with a verb: “Asks”, “Says”, “Wants”, “Mentions”, “Shares”

Coverage requirements for Use when

• Distinct scenarios where the skill activates

• Synonym and vocabulary variants so phrasing differences don’t cause misses

• Indirect or implicit requests where the need is not stated explicitly

• Conversational context: cases where prior exchanges make the skill relevant even if the current message is ambiguous

• Specific source names, file types, or extensions where relevant

Do not use when block

Always include this. It prevents false positives and skill collisions.

• Target at least 4 bullets

• Each bullet should describe a scenario where a different skill, tool, or workflow is the right call

• Where the skill overlaps with another skill, name it explicitly: “(use git-log-helper instead)”

• Avoid vague exclusions like “anything unrelated”. Every bullet should describe a concrete, plausible mismatch

Imagine you have a Google CLI tool that lets you retrieve your Google Tasks:

gog task list [task_list_id]

By default, OpenClaw can make that call using exec. Not only can it get tasks but it can also destroy them. Agents being non-deterministic, that scares me. Let’s lock that exec ability down by editing OpenClaw’s openclaw.json config:

...
"agents": {
  "list": [
    {
      "id": "main",
      "tools": {
        "alsoAllow": ["lobster"],
        "deny": ["exec"] // this entry
      }
    }
  ]
},
...
"tools": {
  "profile": "coding",
  "subagents": {
    "tools": {
      "alsoAllow": ["lobster"],
      "deny": ["exec"] // and this entry
    }
  }
},
...

Let’s review this config from the bottom starting with “tools”. This uses the “coding” profile which gives all agents broad operational functionality like exec, file I/O, or browser access. Next, working backwards, is the “agents” declaration. It has its own “tools” configuration. In both of these places we’ve denied access to exec. Once you start a new session, you can confirm this restriction is in place by asking your agent, “Run ‘echo hello’ and give me the output”. It won’t be able to. exec is now locked down.

Okay, so, if agents can’t use exec how do we let them run tools? Enter Lobster, a workflow shell that lets agents run multi-step tool sequences deterministically with explicit approval checkpoints.

Deterministic with approval checkpoints? Sign me up.

Subscribe now

In the JSON example above, Lobster is already configured with “alsoAllow” which is additive to the other capabilities provided by the “coding” profile. That means Lobster is added to the abilities which are allowed such as browser usage and file I/O. But enabling Lobster is only half the battle. Now we need workflow files to let agents use tools.

I’m not going to hold your hand through installing Lobster; it’s not installed by default alongside OpenClaw. Once you’ve got it, here’s an example Lobster workflow file for creating a Google Task:

name: tasks-add
description: "Create a task in Google Tasks with approval gate"
args:
  title:
    description: "Task title"
  due:
    description: "Due date (YYYY-MM-DD)"
steps:
  - id: build
    run: echo "gog tasks add MY_TASKLIST_ID --title \"${title}\" --due \"${due}\""

  - id: approve
    approval:
      prompt: "Create this task?"
      preview: $build.stdout

  - id: execute
    run: gog tasks add MY_TASKLIST_ID --title "$LOBSTER_ARG_TITLE" --due "$LOBSTER_ARG_DUE"
    condition: $approve.approved

There are three steps in this flow:

1. Output the intended command

2. Ask permission

3. Execute

Steps 1 and 3 are the determinism Lobster introduces. In this example, it controls access to echo and gog (Google CLI). More specifically, the workflow surfaces the command to be executed, we can choose to approve it, and then the workflow will trigger it. By using Lobster we remove non-deterministic tool calls from the agent’s tool-set. That’s the critical takeaway.

The agent still needs to know when to trigger the workflow. That’s where skills come in. Here’s an example skill for creating Google Tasks:

---
name: open-claw-create-task
description: |-
  Creates a Google Task via the Lobster tasks-add workflow.

  Use when the user:
  - Asks to create or add a task
  - Says "remind me to", "add this to my tasks", "put this on my list"
  - Wants to capture something they need to do
  - Says "make a task for", "add a to-do", "don't let me forget to"
  - Mentions a deadline and something they need to get done
  - Wants to track an action item with a due date
---

# Create Task

## Process

1. If the user hasn't provided a task title, ask for one.
2. Ask for a due date. Required. Format must be YYYY-MM-DD.
3. Invoke Lobster with the `tasks-add` workflow:

```json
{
  "action": "run",
  "pipeline": "~/.openclaw/workflows/tasks-add.lobster",
  "argsJson": "{\"title\": \"<task title>\", \"due\": \"<YYYY-MM-DD>\"}"
}
```

Lobster handles confirmation before executing. Never call `gog` directly.

The skill tells the agent when to reach for the workflow and exactly how to invoke it. Lobster handles the rest.

That’s it! Deny access to exec, pair a Lobster workflow with a skill, and you can be confident agent-initiated actions creating, editing, or destroying are 100% approved by you 🦞

Other Helpful Links

• https://docs.openclaw.ai/tools

• https://docs.openclaw.ai/gateway/sandboxing

• https://docs.openclaw.ai/gateway/configuration-reference#agents-list-per-agent-overrides

• https://docs.openclaw.ai/tools/multi-agent-sandbox-tools

• https://docs.openclaw.ai/concepts/architecture

Subscribe now

To start, when you’re interacting with an LLM, like Claude or ChatGPT, you’re talking to an agent. And the back-and-forth between you and the agent is the context. You should care about this context because that’s what the agent knows. If you were to start a new session all that context would be lost. This context is what you’re managing with sub-agents and skills.

I like to think of sub-agents as “side cars”, they run off to the side and have their own context independent of the primary conversation. What that means is the bulk of what they do is lost to the primary context. This context is what you’re managing. You might ask yourself questions like, Do I care about that lost context? Would I prefer to have that knowledge in my primary thread? Is this context something that would improve the final outputs? The answer to these boils down to whether preserving the context will be useful to you in the near-future.

Here are some examples of sub-agents I use to manage context scope, agents that

• capture architectural decision artifacts

• perform adversarial functions on my code

• produce project documentation

• open Pull Requests

If you need to write documentation, have an agent review your code (especially from an adversarial point of view), or fire-and-forget the opening of a PR, you can safely exclude their intermediary thinking as you often only care about the final output.

So those are sub-agents, let’s go further and talk about skills.

Skills are what I like to reach for before getting fancy with sub-agents. Skills are small, focused bits of knowledge that an agent can leverage when necessary. Examples of skills are

• common language conventions

• preferences for writing tests

• composing documentation

• working with data models

Unlike sub-agents, skills load directly into an agent's context; that means you get specialized knowledge without losing valuable context. For example, when I write tests for a has_many relationship I like to be very specific about the check. Say a parent has many children. I don’t want to test that one child exists and I don’t need to instantiate ten. I want precisely two. Why? Because I’ve seen leaky tests before where I might create two objects but there’s a third that sneaks in somehow (overly complex test harnessing). If I don’t check for precisely two and simply look for inclusion then I’ll get a false positive. If I check for one that doesn’t prove there can be many. If I check for precisely two, I catch the case that the test harness itself is bad (i.e. there are more than two). And so I encoded this in a skill’s directive like,

Model relationships (has_many, etc.) must be tested with two associated records. Assert the collection contains exactly both using contain_exactly(item1, item2). Do not use include(one_item); that passes even when the association is broken.

What I get from this is increased certainty that agents performing work for me take advantage of my own experience. In this case, be careful with inclusionary testing.

Subscribe now

What’s more, the nice thing about skills is that they can be referenced by sub-agents. That is, if I eventually want a coding agent that specializes in Ruby, I can tell it to reference all the skills I have for writing Ruby. And that’s where the two ideas link up. You can view skills as building blocks to future agents; mix a little of this knowledge with that knowledge and wrap it up into a single agent that can perform the task on its own.

Ecologists have a name for this: shifting baseline syndrome. Hundreds of years ago, beavers shaped a dramatically different North American landscape. Their dams created wetland ecosystems across regions that are now dry streambeds, vast prairie, or dense forest. As trapping crashed beaver populations, those wetlands vanished and ecosystems collapsed. Each human generation grew up knowing fewer beavers and altered landscapes, accepting that inheritance as the natural state. The baseline had shifted.

Subscribe now

Test suites slow for many reasons, but turnover is what makes those slowdowns invisible. It shifts the baseline. The same mechanism can be seen elsewhere. Consider a team where error messages pipe into a Slack channel. Hundreds arrive daily. Most are informational, some are real errors. Extracting signal from noise becomes impossible. People stop reading it. The problem becomes invisible. New engineers join, see it’s ignored, and learn to ignore it too. The baseline shifts.

The pattern is difficult to see from inside. When someone new asks “what is going on here?” or “why does this take so long?”, the baseline hasn’t been established for them yet. That’s the moment. Listen. Then act: measure the current state, set explicit thresholds for key metrics, and schedule regular baseline audits. Document what “good” looks like before the team falls back into their normal routine.

Ecologists eventually reintroduced beavers to restore damaged ecosystems. Sometimes the equivalent intervention in software is starting fresh. More often, it’s deliberate measurement and conscious resistance to drift.

Let’s say you have some functionality to build for your software product. As nearly all devs do, you grab a story representing what needs to be done and get started. Broadly speaking, you start noodling on how to accomplish this work, you might bounce it off a coworker’s head, and then get to typing. My own take on this process has morphed to include the agent from the outset, not just when I need it to write code. And, most importantly, by the time I’m ready to build, I have a document outlining exactly what I need the agent to do.

Here’s how it goes: when I get started with a story I begin by giving the agent full context. I do this in chat mode instead of coding mode. I do not want it writing yet. After the context, I tell it how I propose to frame the solution. Finally, I begin riffing on the design with the agent, leaning on my many years of software engineering experience. All the while, since I’m having an extended back and forth with the agent, I prefer to talk rather than type.

To be clear, this process isn’t intended to replace collaborating with a coworker, rather, its immediate purpose is to create a markdown file outlining step by step what needs to be done. You see, I do not want an agent running ahead of me, I do not want to lose context on what is written. I want the agent to speed me along, I want to lend it my experience, I want to maintain a high level of context on what’s written, and I want to be confident in the final results. The scaffolding I use to arrive at those final results is what I call the STORY_MEMORY.md file.

Subscribe now

This file is a synthesis of my own experience, conversing back and forth with the agent, and any additional outside influence. Once I’m happy with where I’ve arrived, I have the agent create (or edit) the file. Here’s a contrived example:

# Feature: Article Review (Interactive Q&A)

## Overview
When a user searches for content and an article is returned, they should be able to open a dedicated Article Review page ...

## Implementation Checklist
- [x] **LiveView Module**
  - [x] `article_live.ex` stub created under `web_app/live/`, accepts content id via mount.

- [x] **LiveView Template**
  - [x] `article_live.html.heex` created as a blank template, to be based on `content_review_live.html.heex`.

- [x] **Route Setup**
  - [x] New LiveView route `/article/:id` added to router, following app conventions.

- [ ] **Q&A Interface**
  - [x] Add a form for users to submit questions about the article.
  - [ ] On submit, use the embeddings to find relevant chunks and generate answers.
  - [ ] Display answers and supporting context in the UI.
  - [ ] Write a test to confirm this functionality.

## Notes
- Reuse as much logic and UI as possible from `content_review_live` to keep things simple and maintainable.
- Focus on the article (`content_type: "webpage"`) use case, but keep the design flexible for future expansion.
- Keep the interface clean and focused on Q&A.

The structure is simple. At the least, I like to have an overview of the task, a step by step checklist, and additional notes that might be helpful. I find the [ ] and [x] especially handy to keep track of progress. Most importantly, the work must be broken down step by step. I find this critical for working with agents when programming. It keeps us both focused on atomic tasks. This is how I maintain context, reduce rework, and speed myself along. Otherwise, I’ve found agents are liable to run ahead of me, creating files, building out functionality on their own, making assumptions, and generally leaving me with a tangled web to sort through.

So instead of fighting with an agent to complete story work, create a file dedicated to guiding its output. Do what you always do: think the problem through, plan ahead, break the work into small steps, confer with coworkers, but add the extra step of distilling that into a STORY_MEMORY.md file. This way, you harness the agent's speed while maintaining control through guardrails and manageable chunks of work, while reducing the likelihood of rework and lost context.

Let’s say FGA is the right choice. What are some initial questions to get you on your way?

For me, performance is critical. You have to avoid the “tuple explosion”. It will bring your system to its knees. To this end, think about how often your system will need to ask, Can this user do this thing? Now imagine all the users. All the things. All the checks. Those add up to pressure on the tuple store that must inform the design. It leads me to thoughts like:

• How best to shape graph traversal?

  • Remember, we’re thinking in graphs here

  • Where are the “pivot” points in the models?

  • How can we reduce the number of calls?

  • Can we reduce how much data is retrieved?

  • Deep trees impact performance. Keep traversal limits in mind

• Do users switch contexts (like between organizations)?

• Look for opportunities to reduce tuple count with “cascading” permissions

  • This relates back to tree depth and the “pivot”

  • How will deletion and revocation propagate through the tree

• Can you foresee computed permissions? What might those look like?

• Design around the principle of least privilege

• What low-risk data is worth caching?

Subscribe now

In no universe are these comprehensive. But it’s where my mind drifts first. FGA is a powerful authorization technology. And with that power comes the ability to shoot yourself in the foot blow your foot off. So do your future-self a favor and try to manage the size of your tuple set before it gets out of hand.

I had one partner in mind. Our team had many stories attached to their product. They had a partner program. They were growing. “Perfect”, I thought. And it was, but my naïveté began to show quickly. If I could get some of their Account Executives to chat I could tell them all about our great customer stories. They’ll wave us right in, eager to collaborate. Record scratch. Not so fast.

The first thing to do was to become a partner. Easy enough. At this point, I felt like the gnomes from a South Park episode,

I had to start a campaign. I had to reach out. So I took to my oft-ignored LinkedIn account and began the search for partner Account Executives, Directors, and VPs. I was on the hunt for people who would resonate with my team’s stories. Some semblance of a strategy began to take shape.

I built outreach lists. I tracked the who and when of connections. I worked hard on the narrative to tell. How much was too much? What does rapport look like? What kind of stories land? How much does “What’s In It For Me” play a part? My process was far from perfect. But I was moving from unconscious incompetence to conscious incompetence—the fog was beginning to lift.

Filling in that “phase 2” question mark belies a lot of work. A lot of stress. A lot of stretch. Software had been my comfort place for well over a decade. Leaving it, I discovered I had traded consistent determinism for human dependencies. Test suites gave me instant feedback. An outreach email? Not so much. Was I too wordy? Was I uninteresting? Was the recipient too busy? There is no pass/fail for those.

It’s still a work in progress. It always will be. I still straddle engineering, too. What’s more, that’s been an advantage in navigating customer discussions.

Would I do it again? Yes.

Subscribe now

One thing I’ve learned over my career: people are lazy. And that’s okay. We all are. At different times. Under different circumstances. It’s all too easy to accept the path of least resistance. That’s not a moral failing. Instead of fighting it, we should accommodate it.

In software, think about how we design for users. Like a lazy footpath clipping a turfed corner, we expect users to take the shortest path. So we use progressive profiling to break up long sign-up flows. We offer magic links to bypass forgotten-password hell (adding a new circle to hell in the process). We tune defaults for an immediate, usable experience. When we get it right, we make the right thing easy and the wrong thing hard. Users barely notice. Perfect.

We like to think software engineers are different. We’re smart. We’ll read the docs (what are those?), follow the right process, keep everything tidy. No. We’re not. Get out of here. Worn footpath? Please. More like peregrinated goat trails. There’s a quote getting at this idea, supposedly from Bill Gates (it’s not):

I choose a lazy person to do a hard job. Because a lazy person will find an easy way to do it.

Subscribe now

People are lazy. Find the easy way. Here’s an imagined project structure:

project-root/
├── README.md
├── api/
│   └── README.md
├── adapters/
│   └── README.md
├── pipeline/
│   └── README.md
└── stores/
    └── README.md

You know what’s nice about this? When I’m curious about /api, the explanation is right there, staring me in the face. I don’t need to leave my IDE to spelunk a wiki. The structure is obvious, even if a little repetitive. And once the pattern clicks, it becomes second nature to incorporate into your workflow. If someone forgets to update a README in a PR, it’s easy to spot. Easy to nudge. “Hey, this change should be reflected in the README.”

That’s lazy.

That’s perfect.

It’s important to be clear: EQ isn’t about being nice. And I’m not trying to dig into a candidate’s personal story. I’m trying to understand how they handle ambiguity, conflict, feedback, and failure. Research links traits like self-awareness, regulation, and empathy to real-world performance and long-term success. And when we hire, isn’t that what we actually care about? I can teach software design. I can’t teach emotional regulation or self-awareness. Not at work anyway. Those traits aren’t abstract. They show up in how someone talks about past projects, setbacks, or team dynamics. But you won’t find them on a résumé. You have to ask. You have to listen. You have to engage.

This is where the Big Five Personality Traits shine. It’s my preferred model because its results hold across cultures and contexts. Used well, the five traits (OCEAN) shape both your questions and your interpretation of the answers. You might ask about tradeoffs they’ve made (Openness), how they manage deadlines (Conscientiousness), how they prefer to collaborate (Extraversion), how they handle disagreement (Agreeableness), and what stress does to them (Neuroticism). But you can’t just ask. You have to care. You have to dig in. You have to grab ahold of the thread of their story, find the shape of their arc, not just look for facts.

Subscribe now

Often, interviews cover surface-level questions. They miss the story. I don’t want that. I want to understand where someone’s come from, where they’re going—as best I can given the time constraints. Designing questions that reveal aspects of OCEAN helps me do this. To guide that, I like to ask myself, “what will help uncover this person’s arc?” I don’t want to get to know them as they are right this second, I want their story.

These are example notes I use to find someone’s thread; they help me see beyond the résumé and start to trace their throughline:

Q: When you get stuck on a problem, what’s your approach for getting unstuck?

Traits: O/C/E [these map directly to OCEAN, aspects I’m looking to uncover]

Listen for:

• Grounding in real behaviour

• A non-idealized self-concept

Q: What skill(s) feel just out of reach for you right now?

Traits: O/C/E

Listen for:

• How they frame growth. Do they emphasize team benefit (“I want to help others by learning X”) or personal mastery (“I want to be better at Y”)? Either are valid, but consider the different motivations this reveals

• How is the answer rooted? Does it reflect self-awareness, or is it wrapped in vague ambition?

Potential follow-up: Tell me about a skill you had to stretch for. Why was it important? How’d you develop it?

Q: How do you think people perceive you when you're hashing out ideas with them?

Traits: A/E/N

Listen for:

• Some meta-cognition/social calibration

• Whether they’re aware of how they come across? Do they adapt their style, or are they fixed in how they engage?

• Signs of either self-awareness or blind spots

Judgment isn’t just about spotting bugs or bad smells. It’s learning to weigh one option against another, to see why one solution fits better than the rest, and why certain shortcuts backfire (sometimes spectacularly!). That tends to happen in the messy middle. The part where you spin your wheels before asking for help. That hasn’t evaporated overnight. It’s not gone yet. But it is something we should watch for. It’s a practice ground at risk of being lost. And we need to be sure something equally as useful fills its space.

We have to consciously bring juniors along for this new ride. A ride, in a way, that we’re juniors on! So let’s share our thinking, our tradeoffs, our uncertainty. In this new world where answers are instant, experience becomes harder to acquire. But it is not impossible. We just have to be deliberate.

Let’s be deliberate. Let’s ensure everyone can come along with us.

Subscribe now

I wanted to build a web scraper. This has been solved so many times, but I’m the type that enjoys projects and writing code in my spare time. So there I sat: Windsurf open, an empty project directory in front of me, an empty chat. Pure possibility.

Prior to this, I’d have begun in a single script file—the kind of personal project that is the antithesis of best practices. The file would have grown and grown as I tested and tweaked. It wouldn’t have mattered. It would be all mine. It didn’t need to pass CI. It didn’t need to be grokked by anyone else. It could be a glorious, tangled mess.

As I stared at this empty chat box, though, I had one thought:

Whatever is built here, I want full context.

This one thought, context, framed my interactions with Windsurf as I worked on this project. As I began to think about what I wanted, I decided I didn’t want a single script file. I wanted something more mature. And given my experience, I decided to carefully frame what I wanted to Windsurf. That first message was two paragraphs long. I didn’t save it. But it went something like this:

Okay, I want to build a web scraper in python. It’s going to scrape data off of M website. I want the entry point of the script to be app.py. I want that to load all my dependencies. I want a directory structure like: X, Y, and Z. My authentication model will live in X, my specific scrapers in Y, etc. I want to use playwright for browser interactions. For any class files you create, I only want them stubbed out. I do not want any business logic to be included at all.

The result was the first revelatory moment. In minutes I was hours into my journey. More than that, this new project followed more sustainable practices than a single tangled file. I had crossed a threshold that felt like having discovered programming all over again. It was immediately energizing.

But I wasn’t done. I had only a skeleton of an idea. Again, I thought to myself,

As I keep building, I want full context.

My earliest concern was to avoid something I had seen others do: ask an agent to solve a problem and receive hundreds, if not thousands, of new lines of code in return. Programming this way, it seemed to me, was a surefire way to exist in eternal Peer Review mode. Not exciting.

Instead, I gave the agent a simple, tightly bound directive:

Great, we have a project. Now I want to start simple. When the app first boots, lets open M website in the main.py file. That’s all I want you to do.

That’s all I asked. That’s all it did. No bloat. No surprises. No mental overhead. It was exhilarating. By keeping my questions tightly bounded I could swiftly move through the work while maintaining context.

As I sat there, with the light slowly fading through my window, I got it. It clicked. Agents aren’t for blindly writing code and hoping for the best. They’re collaborators. Think of it like onboarding a junior developer. You don’t dump the whole codebase on them and say “go.” You hand them a small, clearly defined task. You explain the context, the purpose, and the constraints. Then you check in and adjust. It’s the same here.

That’s powerful. A few hours of tinkering has convinced me we’re in the middle of a seismic shift in how software gets written. Like the early days of object-oriented programming, we’re starting to see new patterns emerge for working with agents.

I’ve already stumbled onto one: when you’re starting a project, let the agent handle broad, boilerplate setup above and beyond framework features. Once you’re into feature development, tightly bound your requests to heighten your own context. These two principles alone can dramatically improve the way you build alongside an agent.

A rules file instructs an AI agent how to behave. For example, when you start a new chat with an agent like ChatGPT, it knows nothing about your workflow or the mode you're operating in. Rules files supply that missing context—guiding behavior with your experience and preferences to shape the output. Without these files, the output suffers. In IDEs, rules are typically markdown files (e.g. “general_rules.md”) sent with every request to shape the response.

At a high level, these files capture your preferences around things such as style conventions, architectural choices, and repeatable patterns. What follows are some basic examples to get you thinking.

The Personality

This is at the core of your rules files. It dictates how your AI agent should present itself and behave. A trivial example looks like:

You are a senior software engineer. You approach problem solving from the perspective of deconstruction—you break tasks down into manageable, atomic pieces. You look for simple solutions before conceding to complexity. As you present your suggested solutions, you outline your reasoning and thinking. You engage critically with problems and ensure your solutions are well-reasoned.

Instructions like this can affect how the AI reasons, whether it explains steps, or how assertive it is in making choices. For example, a personality set to “senior engineer who prefers clarity over cleverness” will often avoid terse one-liners in favor of clearer constructs. Depending on your experience, this can be tuned for more effective collaboration.

The Conformist

At the heart of every team, and developer, are conventions and styles that have developed over years. This file isn’t a preferences dump. It’s where hard-won conventions are captured. And it's the file that might see the most amount of churn. It should be actively maintained to ensure it's capturing the team's best practices. Without a file like this, you risk re-litigating the same choices with every code suggestion.

Do you prefer specific patterns in certain circumstances? Outline them here. Do you have patterns, say in testing, that are non-negotiable? Outline them here.

Here's an example:

* When starting a new project, always include the Ruby gem dotenv
* Use string interpolation instead of concatenation
* When creating a class, always stub out a spec file
* Prefer single quotes for strings unless interpolation is needed
* Unless otherwise requested, use the Ruby gem Faraday for HTTP requests
* Use factories (not fixtures) for test data setup
* Document all environment variables in the README or .env.example

The Architect

While the Conformist deals with code style and routine conventions, the Architect governs higher-level design, system behavior, preferences, and architectural principles. This file is especially useful when you have established opinions about how software should be structured, preventing drift and maintaining consistency. For example:

* Use pub/sub for inter-service communication unless strong consistency is required
* Default to simple structs or plain classes; avoid introducing complex base classes or inheritance without need
* For persistent data models, prefer composition over deep nesting
* When creating APIs, enforce idempotency for all POST endpoints unless explicitly marked as one-time actions
* For background jobs, include an exponential retry policy and failure alerting scaffold by default
* When adding a new feature, generate a feature flag scaffold to control rollout

Not every decision is black and white, but these rules can nudge the AI toward your defaults. They're especially useful when consistency matters more than innovation.

Parting Tips

Some advice for putting rules files to work:

• Keep your rules files modular, like outlined above, for easier maintenance

• Treat these files as living documents, update them anytime the AI falls short of your standards

• Consider versioning your rules files in a personal or team repo

  • They can easily be symlinked into new project directories

• Create purpose-built files (e.g. “reviewer.md” or “debugger.md”) for specialized workflows

• Rules files aren’t restricted to developers, they can be useful for project managers or other professionals (e.g. ChatGPT calls them “traits”)

• Add code examples, with instructions, to be explicit in your preferences

Rules files are already essential. They aren’t documentation, they aren’t optional, they’re working memory distilled from decades of collective experience driving the output of the agents your teams use. They’re how things are done.

Performance

These are often the newest, most expensive models to use. They’re built for complexity, for context-heavy tasks that need precision and depth. If I’ve got something big and tangled to accomplish, and I want it done right, I bring out the heavy artillery. It lets me pair my experience with something that doesn’t blink and doesn’t get tired.

Thinking

These versions I love. These models think out loud. You give them a question, and they don’t just spit out an answer—they lay the whole thought process on the table. Brilliant. When you’re venturing into unfamiliar territory you couldn’t ask for more. Like, say, implementing Postgres’ tsvector in Elixir for the first time. You’re not just solving a problem; you’re learning. And better still, you get to catch it when it goes off the rails. You get to push back. You get smarter.

Basic

These models are my go-to grunts. Reliable, cheap, do-as-I-say. I use them when I know exactly what needs to be done—I just don’t feel like doing it. The work is simple, the outcome clear, and I don’t need the thing getting creative. One caveat: I keep them boxed into a single file. I’ve seen too much chaos when a basic model tries to go beyond a single file. They don’t reason well across boundaries. But if it’s a focused task you know your way around, this is your cost-effective, zero-fuss answer.

I read Grace Hopper and The Invention of the Information Age a few years ago. In the 1950s she introduced the first compiler—a program to translate human-friendly, English-like code into machine code. It was a paradigm shift, one that provoked immediate negative reaction:

Reflecting on the negative reactions of some of her fellow programmers, Hopper expressed the belief that arguments focusing on “efficiency” and “creativity” covered far baser motivations: “Well, you see, someone learns a skill and works hard to learn that skill, and then if you come along and say, ‘you don’t need that, here’s something else that’s better,’ they are going to be quite indignant.” In fact, Hopper felt that by the mid 1950s many programmers viewed themselves as “high priests,” for only they could communicate with such sophisticated machines. They served as the intermediaries between user and computer, and automatic programming jeopardized their exclusive position.

These days, no one bats an eye at using compiled languages. We’ve been using Dr. Hopper’s invention to more efficiently write code for decades. Much like the days before her invention of the compiler, writing code today is deep knowledge work. Still, software engineers act as “intermediaries between user and computer.”

Time is a flat circle.

We find ourselves, again, at a clear paradigm shift. By the late 1950s, I bet you could have said the same about compilers as we now say about AI. And much in the same way as those PhD mathematicians writing machine code ultimately had to think more abstractly, we’ll have to shift our thinking. We’ll have to step back from hand-typing every single line of code (minus handy command-line generators) to engaging with AI agents at a more abstracted level.

Time is a flat circle.

Why, now, should we keep building the same old directory structures, tweak migrations, or fiddle with broad-strokes of data models? Let the agents do that, so our deep knowledge work can focus on the trickiest of the tricky—let’s say the 5% of a project where reasoning and creativity matter most.

The LLM is the new compiler.

The agent, the new high-level language.

And we’re about to see a new degree of productivity echoing the gains brought on by Dr. Hopper.

Time is a flat circle.

To begin asking better questions, it helps to understand the concepts that can help get us there—like ken. And no, not the other half of a famous duo! In its simplest form, ken is defined as one’s “range of perception, understanding, or knowledge.” Ken has deep roots, tracing back to kenning, a term with Scottish nautical ties that refers to the limit of our vision at sea—about 20 miles. While nautical history isn’t directly relevant here, connecting dots like this can help cement understanding.

Ken: one’s range of perception, understanding, or knowledge

To complete our question-asking duo, let’s bring naïve realism into the mix. Both a philosophical and psychological concept, it’s the counterpart to ken that, when paired with it, can guide us toward deeper interpersonal connection. For our purposes, we’ll focus on its psychological meaning: the belief that we see the world objectively, without biases or distortions. Naïve realism leads us to assume our perceptions are fully accurate and that those who disagree must be uninformed, irrational, or biased. Acknowledging this bias fosters empathy, encouraging us to see the world through the perspectives of others.

Naïve realism: the tendency to believe one's own senses accurately reflect reality, ignoring the influence of bias and other factors

Now, let’s combine these two ideas. A broad, humble understanding of ken reminds us that our knowledge and perception are inherently limited, much like the horizon seen from a ship. At the same time, naïve realism challenges us to accept that our view of reality is subjective and shaped by personal experiences and biases. Together, these concepts highlight that as we navigate our lives, we experience the world not as it truly is but within the boundaries of our ken. Recognizing this opens the door to curiosity. It invites us to ask deeper, more meaningful questions rather than simply asking more of them. This not only stretches our understanding and expands our ken, but it also fosters deeper connections with those around us.

Where does this lead us? Appreciating naïve realism reminds us that our perceptions may not always reflect reality. Ken, like a spotlight with ourselves at the center, illuminates the limits of our knowledge, a landscape only partially understood. By recognizing the habitual incompleteness of our own understanding, we can better appreciate the same in others. This perspective encourages us to ask questions—not just to fill our own knowledge gaps or challenge biases, but to inspire curiosity and reflection in those we engage with. In doing so, we begin to connect with others more deeply.

Over time, questions like “how are you doing?” will begin to feel colorless and superficial, offering little room for meaningful connection; they’re routine and automatic, often answered without much thought. With practice, though, we might instead ask, “what’s surprised you today?” This type of question invites reflection and opens the door to follow-up: What’s changed for them? What was unexpected or unanticipated? How did it make them feel? Did it interrupt their day or maybe even make it better?

And, of course, what follows is the response. This is where purposeful listening comes into play, allowing us to be more present in the conversation while enabling deeper questions. Much like the horizon at sea marks the limits of our ken, “words with weight” act as signposts, offering glimpses into unexplored conversational terrain. These emotionally charged words guide us along a branching trail, transforming what might have been a brief exchange into a journey through a more vivid landscape—rich with unexpected turns, shadowed valleys, and hidden connections waiting to be uncovered.

We now have a simple framework guiding us toward asking deeper, more meaningful questions, one that acknowledges the subjectivity of our experience and the limits of our knowledge. This empowers us to create richer, more connected conversations, whether at the water cooler, in a line, or even while getting to know a prospective hire.

Together, ken and naïve realism create a foundation for conversations that lead to deeper connection and understanding, providing a pathway to richer, more meaningful relationships. And, now, with all these new signposts to explore, who knows where they’ll lead?