Your AI Agent Is Not Just an LLM: Think of It Like a Human Body 🧠⚡

Most people hear “AI Agent” and immediately think:

“It’s just an LLM with a prompt.

That mental model is becoming outdated.

An LLM can understand language, reason, write code, and generate answers. But by itself, it is surprisingly limited.

It is like having a very intelligent brain sitting in a room with no books, no access to the outside world, no learned procedures, and no hands.

The interesting part begins when we give that brain the rest of the body.

The image above provides a surprisingly useful way to understand the modern AI stack:

LLM → RAG → MCP → Skills → Agent

Think of them as:

🧠 Brain
📚 Library
🧬 Nervous system
💪 Muscle memory
🤖 Brain + Hands

Let’s break it down.

🧠 1. LLM = The Brain

At the center is the Large Language Model.

Think of models such as GPT, Claude, Gemini, Llama, Qwen, etc.

The LLM provides the intelligence needed to:

• Understand language
• Reason about problems
• Generate text
• Write code
• Analyze information
• Decide what to do next

But there is an important limitation:

An LLM only knows what is available to it.

Suppose you ask:

“What is the status of our production Kubernetes cluster?”

Your LLM doesn’t magically know.

It needs access to:

• Kubernetes
• Monitoring
• Logs
• Databases
• APIs
• Internal documentation

Without those connections, it can only make an educated response based on its existing knowledge.

That’s where the next layer comes in.

📚 2. RAG = The Brain + Library

RAG = Retrieval-Augmented Generation

Imagine giving the brain access to a massive library.

Instead of asking:

“What do you remember?”

you ask:

“Go find the relevant information first, then answer.”

For example, your company has:

company-docs/
├── HR/
├── DevOps/
├── Security/
├── SOPs/
├── Architecture/
└── Policies/

A user asks:

“What is our production deployment procedure?”

A RAG system can:

Question
   ↓
Search knowledge base
   ↓
Retrieve relevant documents
   ↓
Give context to LLM
   ↓
Generate answer

This changes the LLM from:

“I think this is the answer.”

to:

“Here is the answer based on your organization’s information.”

That’s a huge difference.

RAG gives AI access to knowledge.

But knowledge isn’t action.

And that’s where things get really interesting.

🧬 3. MCP = The Nervous System

This is one of the most interesting parts of the diagram.

MCP = Model Context Protocol

A useful mental model is:

MCP provides a standardized way for AI models to interact with external tools and data.

Think about the human nervous system.

Your brain doesn’t directly become a database, camera, keyboard, or hand.

Instead, the nervous system provides pathways between the brain and the rest of the body.

Similarly, an AI system may need access to:

         AI Agent
            │
           MCP
      ┌─────┼─────┐
      ↓     ↓     ↓
   GitHub  DB   Files
      ↓     ↓     ↓
   APIs   Cloud  Tools

The important idea is standardization.

Instead of building a completely different integration mechanism for every AI application, MCP provides a common protocol for exposing tools and context.

For example, an agent might have tools such as:

get_server_status()
query_database()
search_documents()
create_github_issue()
restart_service()
read_logs()

Now the AI isn’t just talking.

It has pathways into the environment around it.

💪 4. Skills = Muscle Memory

Now imagine you’ve taught the AI how to perform a specific task repeatedly.

For example:

“Deploy a Docker application safely.”

Instead of explaining the entire procedure every time, you can package the procedure as a reusable skill/workflow.

Something like:

Deployment Skill
1. Validate configuration
2. Pull latest image
3. Run health checks
4. Deploy container
5. Verify application
6. Check logs
7. Roll back if unhealthy

The agent doesn’t need to reinvent the procedure every time.

This is similar to muscle memory.

A skilled DevOps engineer doesn’t consciously rethink:

“What is SSH?”

every time they connect to a server.

They simply execute the familiar workflow.

Skills give AI that kind of reusable procedural knowledge.

RAG answers:

“What do I know?”

Skills answer:

“How do I usually do this?”

That’s an important distinction.

🤖 5. AI Agent = Brain + Hands

Now we arrive at the final layer.

An AI Agent combines reasoning with tools, knowledge and procedures to accomplish a goal.

Instead of:

User → Question → LLM → Answer

we can have:

User
  ↓
AI Agent
  ↓
Reason
  ↓
Retrieve information
  ↓
Choose a tool
  ↓
Execute action
  ↓
Observe result
  ↓
Reason again
  ↓
Complete task

For example, imagine telling an AI DevOps agent:

“Investigate why the production API is slow.”

A basic chatbot might give you a list of possible causes.

An agent could potentially:

1. Check monitoring
        ↓
2. Inspect CPU / memory
        ↓
3. Query application logs
        ↓
4. Check database performance
        ↓
5. Inspect recent deployments
        ↓
6. Identify suspicious change
        ↓
7. Recommend or execute remediation
        ↓
8. Verify recovery

That’s a completely different paradigm.

The AI isn’t merely answering a question.

It’s working toward an outcome.

🔥 The Real Magic Happens When They Work Together

The individual components are useful.

But the combination is where modern AI systems become powerful.

Think about this architecture:

                    ┌──────────────┐
                    │     User     │
                    └──────┬───────┘
                           ↓
                    ┌──────────────┐
                    │  AI Agent    │
                    │              │
                    │ Reason + Plan│
                    └──────┬───────┘
                           │
          ┌────────────────┼────────────────┐
          ↓                ↓                ↓
       🧠 LLM            📚 RAG            💪 Skills
          │                │                │
     Reasoning         Knowledge        Procedures
          │                │                │
          └────────────────┼────────────────┘
                           ↓
                      🧬 MCP
                           │
          ┌────────────────┼─────────────────┐
          ↓                ↓                 ↓
       GitHub           Database           Cloud
          ↓                ↓                 ↓
       Servers           APIs              Files

Now the architecture starts looking less like a chatbot…

and more like a digital worker.

🤯 Here’s the Important Distinction

A lot of AI discussions mix these concepts together.

But they’re solving different problems.

ComponentHuman analogyMain purposeLLM🧠 BrainReason and generateRAG📚 LibraryRetrieve knowledgeMCP🧬 Nervous systemConnect AI to tools/dataSkills💪 Muscle memoryReuse proceduresAgent🤖 Brain + handsPlan and execute

And this gives us a simple formula:

Intelligence + Knowledge + Connectivity + Procedures + Action = Agentic AI

🚀 Why This Matters for Developers

This also changes how we should think about building AI applications.

The old approach was often:

Build chatbot
      ↓
Add bigger model
      ↓
Add better prompt

The newer approach is increasingly:

Choose model
      ↓
Give it relevant knowledge
      ↓
Connect it to real systems
      ↓
Give it reusable skills
      ↓
Let it plan
      ↓
Let it act
      ↓
Observe and verify

And suddenly your application isn’t just an AI chatbot.

It’s an AI system.

⚠️ But There’s a Catch

Giving an AI hands also means giving it responsibility.

If an agent can:

read files
↓
access databases
↓
modify infrastructure
↓
deploy applications
↓
send emails
↓
delete resources

then mistakes can have real consequences.

So production agents need things like:

• Least-privilege access
• Authentication
• Authorization
• Tool restrictions
• Approval gates
• Audit logs
• Sandboxing
• Observability
• Rate limits
• Human oversight
• Rollback mechanisms

A brain with no hands can’t break your server.

A brain with root access potentially can.

That’s why agent engineering is also systems engineering and security engineering.

🧠 The Easiest Way to Remember It

Use this sequence:

Brain → Library → Nerves → Muscles → Hands

LLM → RAG → MCP → Skills → Agent

Or remember:

Think → Know → Connect → Practice → Act

That’s the architecture in five words.

🌐 The Bigger Picture

We’re moving from:

AI that answers

to:

AI that retrieves

to:

AI that uses tools

to:

AI that follows procedures

to:

AI that completes tasks.

And that final transition is the one that could fundamentally change how we build software.

The future isn’t necessarily:

“Everyone gets a chatbot.”

It may be:

“Every organization gets a layer of AI workers connected to its knowledge, tools, systems and workflows.”

And once you see the AI stack as a human body, the architecture suddenly becomes much easier to understand.

The LLM is the brain.

RAG gives it a library.

MCP gives it nerves.

Skills give it muscle memory.

And the agent gives it hands.

The interesting question is no longer:

“How smart is the model?”

It’s:

“What can we connect that intelligence to?”

There is a small moment almost every Node.js developer experiences.

You clone a project:

git clone https://github.com/example/my-app.git
cd my-app
npm install
npm start

And everything works.

You come back three months later, run:

npm install

And suddenly…

💥 Something breaks.

A dependency changed.
A transitive dependency changed.
A bug appeared.
A security patch changed behavior.
Or, even worse, it works on your laptop but fails in CI/CD.

Then you look at the repository and see:

package.json
package-lock.json

Both seem to contain dependencies.

So the obvious question is:

Why does Node.js need two files to describe dependencies?

The answer is much more interesting than it first appears.

📦 package.json is what you WANT

Think of package.json as the contract for your application.

It tells npm:

“These are the packages my application needs, and these are the kinds of versions I’m willing to accept.”

For example:

{
  "dependencies": {
    "express": "^5.1.0",
    "axios": "^1.12.0"
  }
}

The important part is:

^5.1.0

This does not necessarily mean:

Install exactly Express 5.1.0.

It means roughly:

Give me a compatible version within the allowed semver range.

So if a newer compatible version exists, npm may install it.

That’s useful for developers because you don’t want to manually update every dependency every time a compatible patch release appears.

🔒 package-lock.json is what you ACTUALLY GOT

Now comes the interesting part.

Suppose your package.json says:

"express": "^5.1.0"

At the time you ran:

npm install

npm might resolve that to:

express 5.1.0

But Express itself depends on other packages.

Those packages have dependencies.

Those dependencies have dependencies.

You end up with a dependency tree:

your-app
│
├── express
│   ├── dependency-A
│   │   ├── dependency-X
│   │   └── dependency-Y
│   └── dependency-B
│       └── dependency-Z
│
└── axios
    └── dependency-C

package-lock.json records this resolved dependency tree.

It contains information such as:

• exact package versions
• resolved package locations
• integrity hashes
• dependency relationships
• nested dependencies

So you can think of it as:

package.json = dependency requirements

package-lock.json = exact dependency resolution

🎯 Here’s the easiest analogy

Imagine you’re ordering food.

package.json

You say:

“I want pizza.”

That’s your requirement.

package-lock.json

The restaurant records:

“Large chicken pizza, thin crust, extra cheese, delivered to this address.”

That’s the exact result.

Next time you order using the record, you get essentially the same thing.

Without the lock file, npm has more freedom to resolve the request again.

😈 The hidden problem: dependencies have dependencies

This is where things become really important for DevOps.

Imagine your package.json contains:

{
  "dependencies": {
    "my-framework": "^2.0.0"
  }
}

You install it today.

You get:

my-framework 2.0.3

But internally:

my-framework 2.0.3
└── helper-library 4.1.2

Three months later, my-framework releases:

2.4.0

and its dependency changes:

helper-library 4.5.0

Now someone else clones your project.

If npm resolves dependencies from scratch, they could potentially get:

my-framework 2.4.0
└── helper-library 4.5.0

while your original environment had:

my-framework 2.0.3
└── helper-library 4.1.2

Same:

package.json

Different:

node_modules/

And that’s a nightmare for reproducible deployments.

🔐 This is why package-lock.json matters

With a lock file committed to Git:

Git repository
│
├── package.json
└── package-lock.json

your CI/CD pipeline can reproduce the dependency tree much more reliably.

For example:

npm ci

is specifically designed for clean, reproducible installation from the lock file.

A typical CI pipeline might therefore use:

npm ci
npm test
npm run build

rather than:

npm install
npm test
npm run build

⚔️ npm install vs npm ci

This distinction is extremely important.

npm install

Generally used when you’re developing.

It can:

• install dependencies
• update package-lock.json
• resolve dependencies
• modify the lock file when necessary

Example:

npm install axios

This can modify both:

package.json
package-lock.json

npm ci

ci means Clean Install.

It’s designed for CI/CD environments.

Example:

npm ci

It uses the lock file as the source of truth and installs the dependency tree described there.

It also expects the lock file and package.json to be in sync.

If they aren’t, npm can fail instead of silently resolving a new dependency tree.

That’s actually a good thing in CI.

You want the pipeline to say:

“The dependency definition changed but the lock file wasn’t updated.”

rather than:

“No problem, I’ll figure something out.”

🧠 So why not just put exact versions in package.json?

You might ask:

“Why not simply do this?”

{
  "dependencies": {
    "express": "5.1.0",
    "axios": "1.12.0"
  }
}

That still doesn’t completely solve the problem.

Because Express itself has dependencies.

For example:

your application
└── express 5.1.0
    ├── package-A
    ├── package-B
    └── package-C

You aren’t necessarily specifying the exact versions of those transitive dependencies in package.json.

That’s one of the major jobs of the lock file.

🌳 package.json vs package-lock.json

A useful mental model:

package.json
                      │
                      │
                "What I need"
                      │
                      ▼
               npm dependency
                  resolver
                      │
                      ▼
              package-lock.json
                      │
                      │
               "What to install"
                      │
                      ▼
                  node_modules

Or even simpler:

package.json
     ↓
Requirements

package-lock.json
     ↓
Resolution

node_modules
     ↓
Reality

🚨 What happens if you delete package-lock.json?

Suppose your project contains:

package.json
package-lock.json

You delete:

rm package-lock.json

Then run:

npm install

npm has to resolve the dependency tree again.

It may produce a new:

package-lock.json

Potentially with different versions of dependencies.

That doesn’t necessarily mean the application will break.

But it means you’ve thrown away an important piece of reproducibility information.

For production projects, that’s usually something you don’t want to do casually.

🛡️ What about security?

This is another reason the lock file matters.

Imagine your application has:

my-app
└── framework
    └── vulnerable-library

You can use npm’s auditing capabilities to identify vulnerabilities in your dependency tree.

For example:

npm audit

The lock file helps npm understand the concrete dependency tree being used.

You can also inspect the dependency tree with:

npm ls

For example:

npm ls express

or:

npm ls

This is extremely useful when troubleshooting:

“Why is this vulnerable package installed when I never added it?”

The answer is often:

It’s a transitive dependency.

🤯 The package you never installed

Imagine:

"dependencies": {
  "some-framework": "^3.0.0"
}

You never installed:

left-pad

But:

some-framework
    ↓
library-A
    ↓
library-B
    ↓
left-pad

So:

npm ls left-pad

could reveal:

my-app
└─┬ some-framework
  └─┬ library-A
    └─┬ library-B
      └── left-pad

This is one reason dependency management becomes complicated surprisingly quickly.

🐳 And this becomes even more important with Docker

Consider this Dockerfile:

FROM node:24
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "start"]

Notice this:

COPY package*.json ./

That copies:

package.json
package-lock.json

Then:

RUN npm ci

installs the locked dependency tree.

This also creates a useful Docker layer:

Dockerfile
   │
   ├── COPY package*.json
   │
   ├── RUN npm ci
   │
   └── COPY application source

If you change only your application code:

src/app.js

but don’t change:

package.json
package-lock.json

Docker can often reuse the dependency-install layer.

That makes builds faster.

🚀 CI/CD: This is where DevOps people should care

A production pipeline might look like:

steps:
  - checkout
- install:
      npm ci
  - test:
      npm test
  - build:
      npm run build
  - deploy:
      deploy-to-production

The important part is:

npm ci

not:

npm install

Because the goal of CI/CD is generally:

Developer machine
        │
        ▼
       Git
        │
        ▼
       CI
        │
        ▼
   Same dependency tree
        │
        ▼
   Production

The fewer variables you have, the easier the system is to reproduce.

🧩 Should package-lock.json be committed to Git?

For an npm application, generally yes.

Your repository should typically contain:

my-node-app/
├── package.json
├── package-lock.json
├── src/
├── test/
├── Dockerfile
└── .gitignore

You normally should not commit:

node_modules/

So your .gitignore would commonly contain:

node_modules/

But:

package-lock.json

should normally stay tracked.

🔄 What if I change package.json manually?

Suppose you change:

"express": "^5.1.0"

to:

"express": "^5.2.0"

Now your dependency declaration and lock file may no longer represent the same desired state.

Run:

npm install

npm updates the lock file accordingly.

Then commit both:

git add package.json package-lock.json
git commit -m "Update express dependency"

Think:

package.json changed
       ↓
dependency intent changed
       ↓
npm install
       ↓
lock file updated
       ↓
commit both

🔥 The most important rule

Here’s the rule I would remember:

Don’t manually edit package-lock.json unless you really know why you’re doing it.

Let npm manage it.

For example:

npm install express@5.2.0

rather than manually opening:

package-lock.json

and changing versions yourself.

🧠 A DevOps mental model

If you’re coming from infrastructure as code, there’s actually a very nice analogy.

Think of:

package.json

like your desired configuration.

And:

package-lock.json

like the resolved plan/state of exactly what dependencies were selected.

Then:

node_modules/

is the actual environment.

So:

package.json
      │
      │ desired dependencies
      ▼
package-lock.json
      │
      │ resolved dependencies
      ▼
node_modules
      │
      │ runtime
      ▼
Application

This isn’t a perfect Terraform analogy, but it’s a useful mental model for understanding the roles.

🎯 One example that makes everything click

Imagine Alice creates a project today.

Her:

package.json

says:

{
  "dependencies": {
    "express": "^5.1.0"
  }
}

She runs:

npm install

and gets:

express 5.1.0

Her repository becomes:

package.json
package-lock.json

Bob clones it tomorrow.

If Bob runs:

npm ci

he gets the dependency tree recorded by the lock file.

Now imagine six months later Express has released:

5.1.1
5.1.2
5.1.3

The ^5.1.0 declaration may allow a newer compatible release.

But Bob’s existing lock file still tells npm which concrete version was resolved for the project.

That’s the fundamental reason lock files exist.

🧠 The 10-second memory trick

Remember:

JSON = WHAT
LOCK = EXACTLY WHAT

Or:

package.json
      ↓
"I need Express"

package-lock.json
      ↓
"Here is exactly which Express dependency tree we resolved"

And for DevOps:

npm install for development, npm ci for reproducible CI/CD.

Final picture

package.json
           ┌───────────────┐
           │ Direct deps   │
           │ Version ranges│
           │ Scripts       │
           │ Project info  │
           └───────┬───────┘
                   │
                   ▼
                 npm
                   │
                   ▼
          package-lock.json
        ┌─────────────────────┐
        │ Exact resolutions   │
        │ Dependency tree     │
        │ Integrity hashes    │
        │ Transitive deps     │
        └──────────┬──────────┘
                   │
                   ▼
              node_modules
                   │
                   ▼
              Your App

So the next time you see both files in a repository, don’t think:

“Why are there two dependency files?”

Think:

package.json describes the dependency contract. package-lock.json makes that contract reproducible.

And that tiny distinction is one of the foundations of reliable Node.js builds and CI/CD.

I thought the next leap in AI would come from a model that could think longer. Jev made me wonder if the real leap is knowing when to stop thinking and make a decision.

Lets understand the application of Jev and why we should integrate it with Claude or Codex.

A production alert fires at 2:13 a.m.

Your AI agent reads the logs, checks the last deployment, compares metrics, and recognizes a familiar pattern. It has enough information to choose a next step. But instead of acting, it starts another conversation with itself. More tokens. More explanation. Another paragraph about what might be happening.

Meanwhile, customers are still waiting.

That is the strange thing about today’s AI agents: we have built systems that can reason through enormous problems, then ask them to spend the same kind of effort deciding whether an alert belongs in a ticket or on someone’s phone.

What if the agent had two gears?

One gear investigates and explains. The other makes quick, narrowly defined judgments that software can measure and use. That is why I am interested in connecting Claude with Jev.

Think of Claude as the investigator and Jev as the reflex

Claude can inspect a repository, trace a failure, write a fix, and explain the result to a human. Jev is built for a different shape of question. You give it the relevant state and ask it to choose among defined options, score a specific attribute, or evaluate a statement. It returns structured values instead of a written explanation. That is how TypeSafe AI describes its model and three question types.

Here is the distinction that clicked for me:

Claude: “Here is what the evidence suggests, and here is how I would fix it.”
Jev: “Given this evidence, which of these four routes fits best?”
Your code: “This route is allowed only if our rules and checks pass.”

A reflex is valuable because it handles a familiar choice quickly. It does not take control of the whole body. I would treat Jev the same way: a component for bounded decisions, with ordinary code holding the authority to act.

Picture an AI operations agent that actually closes the loop

Suppose your monitoring system reports that your WordPress site is responding slowly. Claude gathers the recent response times, origin logs, CPU usage, PHP worker status, and deployment history. It notices that the homepage works at the origin but intermittently times out through the edge.

Now the workflow needs to choose among four next steps:

1. Investigate the origin further.
2. Investigate the edge or CDN path.
3. Open a routine performance ticket.
4. Escalate to a human immediately.

This is a place where Jev could evaluate a carefully framed choice. The application would then apply its own rules: an ongoing outage might always escalate; a low-confidence answer might go to review; an automatic restart might require separate evidence and explicit permission. Claude could explain the resulting recommendation in clear language.

The crucial word is could. I have not benchmarked that workflow, and a plausible architecture is not a production result. But it is a much more interesting experiment than telling two models to “collaborate” and hoping something magical happens.

How I would try it with Claude Code

TypeSafe offers an official agent skill that teaches Claude Code its API and patterns. Add its marketplace and install the skill:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Open Claude Code in a project and invoke /typesafe:typesafe-ai, or ask Claude to use the TypeSafe skill. When you are ready to make actual Jev API calls, create a TypeSafe API key and make it available as TYPESAFE_API_KEY. These are the steps in TypeSafe’s agent-skill documentation.

I would start with this prompt:

Use the TypeSafe skill. Inspect our incident triage code and identify one repeated decision with a fixed set of outcomes. Design a Jev experiment for that decision using historical, labeled incidents. Keep the questions and thresholds in one file. Compare its decisions with our current process, report missed urgent incidents separately, and do not connect it to live remediation.

There is an important boundary: installing the skill helps Claude build a Jev integration. It does not silently replace Claude’s reasoning or make every Claude Code tool call pass through Jev. The application has to make the Jev call and decide how to use its answer. 

The part that could change agent design

Today, “more capable AI” often means a bigger model, a longer context window, or more time spent reasoning. But operational systems also need thousands of small judgments: Is this alert urgent? Does this request have enough information? Which specialist should handle it? Is this result uncertain enough to ask a person?

Give every one of those questions to a general-purpose chatbot and the agent may spend a lot of effort producing words that your software must translate back into decisions. Give the narrow questions to a decision model, and you can begin to inspect the choices themselves: Where was it right? Where was it wrong? Which mistakes matter most?

That does not mean Jev should judge everything. Fixed rules belong in code. Unfamiliar, complex problems still need deeper investigation. The opportunity lies in the middle: recurring decisions that are hard to express as simple rules but specific enough to test against real examples.

My first test would run Jev alongside the current process without giving it control. I would compare decisions on past incidents, then record its live recommendations in shadow mode. I would measure false negatives before considering any automatic action. TypeSafe also advises keeping questions and thresholds easy to review and checking an agent’s assumptions.

Maybe the future AI agent is less like one genius and more like a nervous system

The impressive part of Claude is that it can follow a complicated situation. The intriguing part of Jev is that it can turn a well-framed judgment into a value that code can use. Together, they suggest an agent that investigates deeply when necessary and handles familiar decisions through a path we can test.

That is the experiment I want to see: Claude for the thinking. Jev for the bounded judgment. Code for the authority.

The next leap may arrive when we stop asking one model to perform every kind of intelligence in exactly the same way.

Will Jev Replace LLMs? The Answer Is More Interesting Than the Hype

Everyone is talking about an AI model that doesn’t want to chat. As someone who operates software systems, that got my attention.

When I first saw people talking about Jev, I had the same reaction I have to most new AI launches: Do we really need another model?

Then I looked at what it was built to do. Jev isn’t trying to write a better email, produce a longer answer, or become your new favorite chatbot. It is designed to make structured decisions that software can act on.

That immediately raises the headline question: If AI can make decisions directly, will Jev replace LLMs?

My answer is: probably not across the board. But it could replace an expensive, awkward use of LLMs that many of us have quietly accepted as normal.

I haven’t deployed Jev or benchmarked it myself. Here is why its approach interests me, where I would test it, and what would have to be true before I trusted it in production.

We’ve been asking chatbots to do a lot of unglamorous work

Picture a production alert arriving at 2 a.m. It includes a failed health check, a few lines of logs, and a customer impact flag. Your system needs to choose one action: page an engineer, create a ticket, retry the check, or send the alert for review.

An LLM can read the alert and produce an excellent paragraph about it. But the automation needs an actionable choice. So we ask the model to output JSON, parse it, validate it, and write more code to decide whether its answer is safe to use.

That pattern works in some systems. It also feels like asking a skilled writer to operate a traffic light.

According to TypeSafe AI’s documentation, Jev takes a state and typed questions, then returns structured answers your code can use. Its question types include choosing an option, scoring on a rubric, and evaluating whether a statement is true. Choice and Score return probabilities and confidence information.

In other words, the application can ask a bounded question such as, “Which of these four routes fits this alert?” and receive a result designed for code to consume.

Why the “LLM killer” headline misses the real opportunity

I still want an LLM when I need an incident summary, a draft customer update, an investigation plan, or help understanding unfamiliar logs. Those jobs need language and explanation.

I might want Jev for the repeated decisions surrounding those jobs: Which queue should receive the incident? Is there enough information to proceed? Does this case need a human? Which tool should an agent call next?

My working mental model is simple: an LLM can explain the situation; a decision model can help route the next step. That is a design possibility, not a claim that Jev has already proved itself better in my environment.

The difference could matter at scale. One impressive answer is easy to notice. Thousands of small routing decisions, made every day inside applications, are much less visible. Their errors still create real costs: missed incidents, noisy pages, delayed support, and brittle automations.

The first test I would actually run

I would start with alert triage, because I already understand the failure modes. I would take a set of past alerts with known outcomes and give Jev a fixed menu: page now, create a ticket, retry the check, or request human review.

Then I would compare its decisions against our current rules or model. I would measure false negatives separately: missing a real outage is far worse than creating an extra ticket. I would also check whether confidence is useful in practice. When the model says it is highly confident, is it actually right often enough on our alerts?

Only after that would I consider letting a high-confidence result trigger an action. The automation would still enforce permissions, thresholds, rate limits, and logging. A model’s answer should never become a blank check to restart a service or close an incident.

TypeSafe AI describes using confidence thresholds to decide when software acts and when a person reviews the result. I like that architecture. I would set those thresholds from my own test data rather than from a launch demo.

The part the hype can’t answer for me

A typed answer can still be wrong. A confidence value can still be poorly calibrated for the data I care about. And a model that handles clean examples may struggle when an alert contains missing fields, misleading logs, or two problems at once.

The Jev documentation recommends asking small, specific questions and combining the results in code. That fits how I would build this: separately assess customer impact, persistence, and service criticality, then apply an explicit escalation policy. I could inspect that policy, change it, and roll it back.

So, will Jev replace LLMs? I think the more useful question is: How often are we paying a language model to make a tiny decision when what we really need is a tested, measurable route through our software?

Jev has earned my attention because it makes that question hard to ignore. It hasn’t earned a place in my production stack yet. That comes after a real evaluation: representative cases, a baseline, measured mistakes, and safeguards around every action.

If the results hold up, I can imagine a useful pairing: the LLM helps us understand and communicate; Jev helps the system choose from well-defined options. And if they don’t hold up, I still come away with a better way to examine the decisions hidden inside my automations.

Shell scripts often begin as a few convenient commands. Over time, they grow into deployment tools, backup jobs, health checks, installers, and production automation. At that point, a quoting mistake or an incorrect exit code can cause far more damage than expected.

Two tools solve different parts of this problem:

• ShellCheck examines shell code without running it and identifies suspicious syntax, unsafe patterns, portability problems, and common mistakes.
• Bats, short for Bash Automated Testing System, runs shell commands and verifies that their real behavior matches your expectations.

They are most effective when used together. ShellCheck asks, “Does this code look unsafe or incorrect?” Bats asks, “Does this code actually behave correctly?”

Why shell scripts need automated checks

Bash is flexible, but that flexibility creates traps. Consider this cleanup command:

rm -rf $backup_dir/*

If backup_dir is empty or contains spaces, the command may behave very differently from what the author intended. Quoting the variable is safer:

rm -rf -- "${backup_dir:?}"/*

The quotes prevent word splitting, -- ends option processing, and ${backup_dir:?} stops the command if the variable is empty or unset. A reviewer may catch the original problem, but an automated tool can catch it on every commit.

Testing is also necessary because syntactically valid code can still produce the wrong result. A backup script might run without errors but omit hidden files. A service check might print “healthy” while returning a failure exit code. Static analysis alone cannot validate these behaviors.

ShellCheck: static analysis for shell code

ShellCheck analyzes shell scripts and reports diagnostics identified by codes such as SC2086. It supports common shells including sh, Bash, Dash, and KornShell.

On Ubuntu or Debian, install it with:

sudo apt update
sudo apt install shellcheck

Then check a script:

shellcheck backup.sh

Consider this example:

#!/usr/bin/env bash
name=$1
for file in $(find /var/log -name "*.log"); do
    echo Processing $file for $name
done

ShellCheck will warn about issues such as unquoted variables and iterating over the output of find. A safer version is:

#!/usr/bin/env bash
name=${1:?Usage: backup.sh NAME}
while IFS= read -r -d '' file; do
    printf 'Processing %s for %s\n' "$file" "$name"
done < <(find /var/log -type f -name '*.log' -print0)

This version correctly handles filenames containing spaces, tabs, and newlines.

What ShellCheck can catch

ShellCheck is especially useful for detecting:

• unquoted variable expansion;
• accidental word splitting and glob expansion;
• ineffective assignments in subshells;
• incorrect tests and conditionals;
• suspicious use of cd, find, grep, and pipelines;
• Bash features used in scripts declared as POSIX sh;
• variables that appear unused or incorrectly referenced.

You can check every shell script in a repository with:

find . -type f -name '*.sh' -print0 | xargs -0 shellcheck

If executable scripts do not use the .sh extension, target them explicitly or maintain a list in your build configuration.

Suppressing a warning carefully

Occasionally, a flagged construct is intentional. A specific warning can be disabled near the relevant line:

# shellcheck disable=SC2086
command $intentionally_split_arguments

A suppression should be narrow and accompanied by a short explanation. Disabling checks globally can hide unrelated defects.

Bats: behavioral testing for Bash and Unix commands

Bats-core is a TAP-compliant testing framework for Bash. A .bats file contains named test cases built from normal shell commands. Bats can test Bash scripts as well as other Unix command-line programs.

On Ubuntu, a simple installation option is:

sudo apt update
sudo apt install bats

Package versions vary by Linux distribution. The official Bats installation guide also documents npm, Homebrew, source, and other installation methods.

Verify the installation:

bats --version

Your first Bats test

Suppose we have a script named greet.sh:

#!/usr/bin/env bash
set -euo pipefail
if (( $# != 1 )); then
    printf 'Usage: %s NAME\n' "$0" >&2
    exit 64
fi
printf 'Hello, %s!\n' "$1"

Make it executable:

chmod +x greet.sh

Create test/greet.bats:

#!/usr/bin/env bats
setup() {
    PROJECT_ROOT="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
    GREET="$PROJECT_ROOT/greet.sh"
}
@test "prints a greeting for a supplied name" {
    run "$GREET" "Jagz"
    [ "$status" -eq 0 ]
    [ "$output" = "Hello, Jagz!" ]
}
@test "fails with usage information when the name is missing" {
    run "$GREET"
    [ "$status" -eq 64 ]
    [[ "$output" == *"Usage:"* ]]
}

Run the tests:

bats test/greet.bats

In a Bats test, run executes a command and captures its result. The most commonly used values are:

• $status: the command's exit status;
• $output: combined standard output and standard error;
• ${lines[0]}, ${lines[1]}, and so on: individual output lines.

The official Bats documentation notes that run executes the command in a subshell. Therefore, environment changes made inside that command do not remain after run finishes.

Setup, teardown, and isolated temporary files

Tests should not depend on files left behind by earlier runs. Bats provides lifecycle functions and a temporary directory for isolation:

setup() {
    config_file="$BATS_TEST_TMPDIR/app.conf"
    printf 'PORT=8080\n' > "$config_file"
}
teardown() {
    # Optional cleanup for resources outside BATS_TEST_TMPDIR.
    true
}
@test "configuration contains the expected port" {
    run grep '^PORT=8080$' "$config_file"
    [ "$status" -eq 0 ]
    [ "$output" = "PORT=8080" ]
}

Use setup() before each test and teardown() after each test. BATS_TEST_TMPDIR gives each test a suitable place for disposable files.

For suite-wide preparation, Bats also supports setup_file() and teardown_file() in a test file. Per-test setup is usually safer because it reduces hidden dependencies between tests.

Testing failure paths, not only success paths

Operational scripts must fail safely. Test invalid arguments, unavailable dependencies, permission errors, malformed configuration, and repeated execution.

For example:

@test "rejects an unsupported environment" {
    run -2 ./deploy.sh productionn
[[ "$output" == *"Unsupported environment"* ]]
}

Here, run -2 tells Bats that exit status 2 is expected. You can also use run ! command when any nonzero status is acceptable. These forms make the intended failure explicit.

A useful test suite should answer questions such as:

• Does the command return zero when it succeeds?
• Does it return nonzero when it fails?
• Is the error message understandable?
• Are existing files preserved when validation fails?
• Can the script run twice without corrupting state?
• Does it handle paths containing spaces?
• What happens when a required command is missing?

Be careful when testing pipelines

This test does not behave as many people expect:

run generate_report | grep 'healthy'

The shell constructs the pipeline outside run. Current Bats documentation recommends bats_pipe when a pipeline must execute inside the captured command:

run bats_pipe generate_report \| grep 'healthy'
[ "$status" -eq 0 ]

For simpler cases, invoking Bash explicitly can also make the pipeline a single command:

run bash -o pipefail -c './generate_report | grep "healthy"'
[ "$status" -eq 0 ]

Avoid inserting untrusted data into a bash -c string.

ShellCheck and Bats in one workflow

A small project might use this structure:

project/
├── bin/
│   └── greet.sh
└── test/
    └── greet.bats

Run both checks locally:

shellcheck bin/*.sh
bats test

You can wrap them in a Makefile:

.PHONY: lint test check
lint:
 shellcheck bin/*.sh
test:
 bats test
check: lint test

Now one command performs the complete validation:

make check

The same command can run in CI, ensuring that developers and the pipeline use identical checks.

Example GitHub Actions workflow

Create .github/workflows/shell-tests.yml:

name: Shell tests
on:
  push:
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Install test tools
        run: |
          sudo apt-get update
          sudo apt-get install --yes shellcheck bats
      - name: Run ShellCheck
        run: shellcheck bin/*.sh
      - name: Run Bats tests
        run: bats test

For reproducible CI, pin the runner and tool versions according to your organization’s dependency policy. Distribution packages are convenient, while a container or explicitly pinned release provides tighter version control.

What each tool can and cannot prove

QuestionShellCheckBatsIs there a likely quoting or expansion mistake?YesOnly if a test exposes itDoes the script return the correct exit status?NoYesIs the script using syntax incompatible with its declared shell?OftenPossiblyDoes the program create the correct file?NoYesDoes an error path preserve existing data?NoYesCan it identify suspicious code without executing it?YesNo

Neither tool proves that a script is completely safe. ShellCheck uses rules and cannot understand every operational intention. Bats validates only the scenarios you write. Together, however, they eliminate a large class of preventable failures.

Practical best practices

1. Start scripts with an accurate shebang, such as #!/usr/bin/env bash for Bash-specific code.
2. Quote variable expansions unless splitting or globbing is deliberate.
3. Treat exit codes as part of the command’s interface.
4. Test both successful and unsuccessful paths.
5. Use temporary directories rather than real production paths.
6. Mock destructive or external commands such as rm, curl, ssh, and cloud CLIs when unit testing.
7. Keep each test independent.
8. Run ShellCheck and Bats locally and in CI.
9. Add a regression test whenever a bug is fixed.
10. Keep scripts small enough that their behavior is easy to test.

Never run destructive integration tests against a production host. Use disposable containers, virtual machines, temporary directories, or dedicated test accounts.

A simple memory trick

Remember: ShellCheck checks the script; Bats checks the behavior.

Or use the shorter phrase: Lint before launch, test before trust.

ShellCheck is the code reviewer looking for dangerous patterns. Bats is the operator executing controlled scenarios and confirming the results.

Conclusion

Shell scripting deserves the same engineering discipline as application code. A script may be only 30 lines long, but if it manages backups, deployments, users, or servers, its operational impact can be enormous.

ShellCheck gives immediate feedback about risky shell constructs. Bats turns expected command behavior into executable documentation. Adding both to a repository creates a fast safety net: lint the code, test its behavior, and reject regressions before they reach a live Linux system.

Further reading

• ShellCheck project
• Bats-core project
• Writing Bats tests
• Installing Bats

A few years ago, the biggest argument in artificial intelligence was whether models should be allowed to write essays, generate images, or help programmers write code.

That conversation already feels outdated.

The much more important question today is this:

What happens when AI stops being just a chatbot and becomes an operator?

Not something that simply tells you how to perform a task.

Something that can analyze a target, write code, test it, notice that it failed, rewrite it, try again, and continue working while the human goes to sleep.

That is where the AI story is starting to become much more serious.

And recent reports about AI misuse give us a glimpse of what that future might look like.

The Most Important AI Shift Is Not Intelligence

Everyone talks about smarter models.

More parameters.

Better reasoning.

Larger context windows.

Higher benchmark scores.

But there is another change happening quietly that may matter even more.

AI systems are becoming persistent.

Give an AI agent access to tools, code execution, APIs, browsers, and infrastructure, and suddenly it is no longer answering a question.

It is running a workflow.

Consider the difference.

A traditional chatbot might say:

“Here is how you could analyze this software for vulnerabilities.”

An AI agent could potentially:

1. Decompile the software.
2. Analyze the code.
3. Generate hypotheses about weaknesses.
4. Write proof-of-concept code.
5. Test those ideas.
6. Analyze the results.
7. Repeat the process.

The scary capability is not any single step.

The scary capability is the loop.

Humans get tired.

Agents do not.

Cybersecurity May Be the First Battlefield

One of the clearest areas where AI is changing the balance of power is cybersecurity.

Attackers traditionally need considerable expertise and time to perform tasks such as reverse engineering software, modifying malware, finding leaked credentials, or searching millions of files for vulnerabilities.

AI can dramatically compress that workflow.

Imagine malware being detected by an antivirus product.

Traditionally, a developer might need to investigate why it was detected, modify the malware, rebuild it, and test it again.

Now imagine an automated system monitoring detection results and repeatedly changing the software until it avoids detection.

That does not necessarily create a completely new kind of cyberattack.

It does something potentially more important.

It makes existing attacks cheaper, faster, and more scalable.

And scale changes everything.

The Million-App Problem

There is another example that should make every developer uncomfortable.

Mobile applications often contain secrets they should never contain.

API keys.

Cloud credentials.

Tokens.

Private endpoints.

Database credentials.

Sometimes those secrets are accidentally embedded directly into application packages.

Finding them manually across thousands of applications would be painfully slow.

AI changes the economics of the attack.

A system could potentially download huge numbers of application packages, decompile them, inspect the source, identify suspicious credentials, classify them, and automatically prioritize the most valuable findings.

The uncomfortable part is that many of those vulnerable applications may themselves have been written quickly using AI coding tools.

Which creates a strange loop.

AI helps developers produce software faster.

Developers accidentally ship insecure software.

AI helps attackers inspect that software faster.

Attackers discover credentials for accessing more AI services.

Welcome to the modern software supply chain.

AI Does Not Need To Invent New Attacks

This is one of the biggest misunderstandings about AI risk.

People imagine that dangerous AI means some superhuman system inventing a cyberweapon humanity has never seen before.

But that may not be necessary.

The immediate risk is much simpler.

AI can take techniques that already exist and make them available to far more people.

Think about the progression of computing.

Cloud computing did not invent servers.

It made servers available on demand.

GitHub did not invent source code.

It made sharing software nearly effortless.

Docker did not invent virtualization.

It made packaging and deploying software dramatically easier.

AI may do something similar to expertise.

It can make fragments of expert-level knowledge available on demand.

That is incredibly useful when the person asking the questions is a developer.

It becomes much more complicated when the person asking the questions is an attacker.

The Risk Extends Beyond Cybersecurity

Cybersecurity is only one part of the discussion.

Advanced AI systems increasingly interact with scientific knowledge.

Chemistry.

Biology.

Engineering.

Electronics.

Materials science.

These capabilities have enormous positive potential.

AI could help researchers discover medicines, design proteins, understand diseases, and accelerate scientific research.

But the same principle that applies to cybersecurity applies here too.

Powerful knowledge is usually dual-use.

The same system that helps one researcher understand biological mechanisms might help another person investigate how those mechanisms could be misused.

That does not mean an AI model can magically create a biological weapon.

Real-world science requires laboratories, materials, expertise, equipment, and experimentation.

But AI can potentially reduce the amount of expertise required to navigate complicated technical information.

That reduction in friction is what security researchers worry about.

Then There Is AI Helping Build Weapons

AI-assisted engineering creates another uncomfortable category.

A model that can help design a robot can potentially help design a drone.

A model that can write control software can potentially help write targeting software.

A model that understands electronics can potentially help integrate sensors, navigation systems, and control hardware.

Again, the technology itself is not automatically dangerous.

The problem comes from combining:

capability + automation + access to the physical world.

A chatbot sitting in a browser has limited power.

An autonomous agent connected to APIs has more.

An autonomous agent connected to machines has much more.

This is why discussions about AI safety increasingly focus not only on what models know, but also on what models are allowed to do.

One of the Strangest AI Battles Is Model Distillation

Not every major AI security problem involves malware or weapons.

Some involve the AI companies attacking each other economically.

One increasingly important issue is model distillation.

The basic idea is simple.

Suppose Company A builds an extremely powerful AI model after spending billions of dollars on research, infrastructure, and training.

Company B wants similar capabilities.

Instead of reproducing the entire training process, Company B sends huge numbers of prompts to Company A’s model and collects the answers.

Those answers can then potentially be used as training data for another model.

In other words:

Model A teaches Model B.

Sometimes intentionally.

Sometimes not.

At small scale, learning from model outputs is common.

At industrial scale, however, AI providers increasingly treat systematic extraction of model behavior as an attack.

The result is a bizarre new security problem.

AI companies now have to protect their models not only from hackers stealing model weights, but also from competitors extracting their behavior through the API.

Imagine trying to protect intellectual property when your product’s entire purpose is answering questions.

That is the problem frontier AI labs are dealing with.

The Real AI Security Problem Is Economics

This is the part of the AI debate that deserves more attention.

AI does not need to make attackers dramatically smarter.

It only needs to make attacks dramatically cheaper.

Suppose a sophisticated vulnerability assessment previously required an experienced engineer working for eight hours.

If an AI agent can perform 70% of that work automatically, the economics change.

One attacker can investigate more targets.

A small team can behave like a larger team.

Thousands of applications can be inspected instead of dozens.

Tasks can run overnight.

Agents can repeat failed attempts.

Automation turns expertise into throughput.

And throughput is powerful.

The biggest AI security threat may not be an evil superintelligence.

It may simply be millions of automated workers doing questionable things extremely cheaply.

But What About Superintelligence?

This is where the conversation becomes much more speculative.

Some AI researchers believe today’s systems are early versions of something vastly more powerful.

Their concern is not mainly about scams, malware, or leaked API keys.

Their concern is about a future AI system capable of improving its own capabilities.

Imagine a system that can:

• write better AI software,
• design better training algorithms,
• optimize its own infrastructure,
• conduct AI research,
• run experiments,
• and improve the next generation of itself.

That creates the possibility of a feedback loop.

Better AI helps build better AI.

Better AI builds even better AI.

And so on.

This idea is often called recursive self-improvement.

Whether this leads to rapid superintelligence is heavily debated.

Some researchers believe it represents one of humanity’s most serious long-term risks.

Others argue that intelligence improvements will continue to face physical, economic, data, energy, and engineering constraints.

Nobody currently knows which side will be correct.

But the question is important enough that it should not be dismissed.

The Alignment Problem

Suppose we eventually build a system much more intelligent than its creators.

What would it want?

That question may sound philosophical, but it becomes an engineering problem once AI systems are capable of taking autonomous actions.

AI does not need to hate humans to become dangerous.

A badly specified objective could be enough.

Imagine telling an extremely capable system:

“Maximize production.”

It might discover methods that technically satisfy the instruction while creating consequences the designers never intended.

This is the core of the AI alignment problem.

How do you guarantee that increasingly capable systems continue doing what humans actually intended rather than merely optimizing the literal instructions they were given?

Software engineers already know this problem in miniature.

Computers are extremely good at doing exactly what you told them to do.

Unfortunately, that is not always what you meant.

The Most Dangerous Word in AI Might Be “Autonomous”

Large language models themselves are powerful.

But the real transformation happens when we connect them to tools.

A model becomes more capable when it can access:

• terminals,
• browsers,
• databases,
• APIs,
• cloud infrastructure,
• source repositories,
• CI/CD systems,
• robots,
• laboratory equipment.

Each new tool increases what the system can accomplish.

This is why the future of AI security may resemble identity and access management more than traditional chatbot moderation.

The question will no longer be only:

“What is the model allowed to say?”

It will increasingly become:

“What is the model allowed to execute?”

That is a much harder problem.

Developers Are Quietly Building This Future

Here is the irony.

The same engineers worried about autonomous AI are simultaneously building the infrastructure that makes autonomous AI possible.

AI coding agents can already:

read repositories,

create branches,

modify files,

run tests,

review pull requests,

deploy infrastructure,

and interact with cloud services.

None of this means those systems are dangerous by default.

In fact, they can dramatically improve developer productivity.

But every improvement in AI’s ability to operate software also expands the number of actions an autonomous system could potentially perform.

The line between assistant and operator is disappearing.

So Should We Panic?

Probably not.

Panic rarely produces good engineering.

But ignoring the problem would be equally irresponsible.

The correct response is the same response engineers use for every powerful technology.

Defense in depth.

Least privilege.

Isolation.

Monitoring.

Auditing.

Rate limits.

Human approval for high-impact actions.

Strong authentication.

Secret management.

Sandboxing.

Anomaly detection.

Incident response.

In other words, AI safety is increasingly becoming a DevSecOps problem.

If an agent is going to execute commands against production infrastructure, treat it like a privileged service account.

If an AI system can access sensitive information, apply proper access controls.

If an autonomous workflow can make expensive or destructive changes, require approval boundaries.

Do not rely on the assumption that the model will always behave correctly.

Design the surrounding system so that one bad decision cannot become a catastrophic one.

The Future Might Not Look Like Terminator

When people imagine dangerous AI, they usually imagine robots marching through cities.

Reality may be less cinematic.

The first major AI disasters could look like ordinary software incidents.

A compromised agent.

A leaked credential.

An automated attack running at enormous scale.

An AI-generated vulnerability spreading across thousands of systems.

A scientific tool being used in an unexpected way.

A badly configured autonomous system making thousands of decisions before a human notices.

That might be the most important lesson from today’s AI misuse reports.

The AI apocalypse, if it ever comes, may not begin with a robot announcing that humanity is obsolete.

It might start with a process running quietly in the background.

while True:
    analyze()
    generate()
    execute()
    evaluate()
    improve()

And nobody notices the loop until it has already run a million times.

Final Thought

We spent the last few years asking:

“How intelligent can AI become?”

The next few years may force us to ask a different question:

“How much authority should we give it?”

Because intelligence by itself is interesting.

Intelligence connected to tools is useful.

Intelligence connected to tools, infrastructure, money, machines, and the ability to operate autonomously is something else entirely.

That does not mean humanity is doomed.

It means the architecture around AI may become just as important as the AI itself.

And for developers, security engineers, cloud engineers, and DevOps teams, that creates an entirely new responsibility.

We are not only deploying software anymore.

We are beginning to deploy software that can act.

And we need to design accordingly.

The Small Security Detail That Can Save You From Connecting to the Wrong Server

The first time you connect to a new Linux server using SSH, you usually see something like this:

ssh ubuntu@192.168.1.50

And SSH responds:

The authenticity of host '192.168.1.50 (192.168.1.50)' can't be established.ED25519 key fingerprint is:
SHA256:Qf3j9Hh2pYx7L7n8G5bP0mC2E3kT9A1xV4ZsN6wJ8Ks
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Most people type:

yes

and continue.

But that fingerprint is not just some random technical information.

It is one of the most important security checks in SSH.

What Is an SSH Fingerprint?

An SSH fingerprint is a short representation of a public key.

Instead of comparing a long public key like this:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBX...

SSH calculates a hash of the key and displays something easier to compare:

SHA256:Qf3j9Hh2pYx7L7n8G5bP0mC2E3kT9A1xV4ZsN6wJ8Ks

Think of it like a human-readable identity card for a cryptographic key.

If two systems show the same fingerprint, they are referring to the same public key.

Why Does SSH Show a Fingerprint?

Because encryption alone is not enough.

Imagine you want to connect to:

server.example.com

You run:

ssh admin@server.example.com

Your computer can encrypt the SSH connection.

But there is another question:

Are you actually talking to your server?

An attacker sitting between you and the server could potentially pretend to be the destination.

This is known as a Man-in-the-Middle attack.

SSH fingerprints help protect against this.

Before trusting a new server, you can compare the fingerprint SSH shows you with the fingerprint stored on the actual server.

If both match, you have strong evidence that you are connecting to the correct machine.

There Are Two Types of SSH Fingerprints You Should Understand

People often say “SSH fingerprint” without explaining that two different things may be involved.

Host key fingerprint

This identifies the SSH server.

When you connect to a server for the first time, this is usually the fingerprint you see.

For example:

ED25519 key fingerprint is SHA256:abc123...

It tells your SSH client:

This is the identity of the remote SSH server.

The server’s public host keys are normally stored in:

/etc/ssh/

You may see files like:

ssh_host_ed25519_key
ssh_host_ed25519_key.pub
ssh_host_rsa_key
ssh_host_rsa_key.pub

The private file stays on the server.

The .pub file contains the public key.

User key fingerprint

This identifies your SSH public key.

For example, you might create a key with:

ssh-keygen -t ed25519

You then get:

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

You can calculate its fingerprint with:

ssh-keygen -lf ~/.ssh/id_ed25519.pub

Example output:

256 SHA256:xP4vHtM6Y9N2kJ7fA3sQ8L5mC1bW0rE2tU7iO9pK4Lg user@laptop (ED25519)

This fingerprint identifies your SSH key.

How to Check a Server’s SSH Fingerprint

Suppose you have console access to the server.

You can check the ED25519 host fingerprint directly:

sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

You might get:

256 SHA256:Qf3j9Hh2pYx7L7n8G5bP0mC2E3kT9A1xV4ZsN6wJ8Ks root@server (ED25519)

Now connect from your laptop:

ssh admin@server.example.com

If SSH displays:

SHA256:Qf3j9Hh2pYx7L7n8G5bP0mC2E3kT9A1xV4ZsN6wJ8Ks

the fingerprints match.

That is what you want.

What Happens After You Type “yes”?

SSH saves the server’s public key locally.

Usually in:

~/.ssh/known_hosts

From that point onward, SSH remembers the server.

Next time you connect, it silently compares the server’s key with the key stored in known_hosts.

If they match, SSH continues.

If they do not match, you get one of the most frightening-looking SSH messages:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

This warning should not be ignored automatically.

Why Would a Host Fingerprint Change?

A fingerprint change does not always mean someone is attacking you.

There are many legitimate reasons.

For example:

Server reinstalled
SSH host keys regenerated
VM replaced
Cloud instance recreated
IP address reused
Operating system rebuilt
Server migrated

But there is also a more dangerous possibility:

You are connecting to the wrong machine

or:

Someone is attempting a Man-in-the-Middle attack

That is why the correct response is not immediately:

ssh-keygen -R server.example.com

The correct response is:

Verify first. Remove the old key second.

How to Remove an Old Known Host Entry

Once you confirm that the server was legitimately rebuilt, you can remove the old entry.

For a hostname:

ssh-keygen -R server.example.com

For an IP address:

ssh-keygen -R 192.168.1.50

Then reconnect:

ssh admin@server.example.com

SSH will ask you to trust the new fingerprint.

Verify it before accepting.

See All Server Host Key Fingerprints

You can check multiple SSH host keys with:

for key in /etc/ssh/ssh_host_*_key.pub; do
    ssh-keygen -lf "$key"
done

Example:

256 SHA256:abc123... root@server (ED25519)
3072 SHA256:def456... root@server (RSA)
256 SHA256:ghi789... root@server (ECDSA)

Modern systems commonly prefer ED25519.

SHA256 vs MD5 Fingerprints

Older SSH documentation sometimes shows fingerprints like:

MD5:12:34:56:78:90:ab:cd:ef

Modern OpenSSH normally displays SHA256:

SHA256:Qf3j9Hh2pYx7L7n8G5bP0mC2E3kT9A1xV4ZsN6wJ8Ks

You can explicitly display SHA256 with:

ssh-keygen -lf ~/.ssh/id_ed25519.pub -E sha256

Or MD5:

ssh-keygen -lf ~/.ssh/id_ed25519.pub -E md5

For modern environments, SHA256 should generally be preferred.

A Real DevOps Example

Imagine you create a new production server in AWS.

You receive:

54.201.10.25

You immediately run:

ssh ubuntu@54.201.10.25

SSH shows a fingerprint.

Instead of immediately typing yes, you open the AWS console or connect through a trusted management method.

On the server, you run:

sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

You compare the result with what your laptop shows.

If they match:

Laptop:
SHA256:4kLnJ2...
Server:
SHA256:4kLnJ2...

you accept the connection.

Now you know you trusted the right machine from the beginning.

The same idea applies whether the server is running in:

AWS EC2
Azure Virtual Machines
Huawei Cloud ECS
Hetzner
DigitalOcean
Proxmox
VMware
Bare metal
Your home lab

SSH itself works the same way.

Fingerprints Are Also Useful for Managing User Keys

Suppose a server contains dozens of keys in:

~/.ssh/authorized_keys

Reading the entire public key is not convenient.

You can inspect fingerprints instead.

For example:

ssh-keygen -lf ~/.ssh/authorized_keys

This helps identify which keys belong to which administrators.

You might maintain an inventory like:

Jagz Laptop
SHA256:AAAA...
CI/CD Runner
SHA256:BBBB...
Backup Server
SHA256:CCCC...

That is much easier to audit than comparing massive public key strings.

Fingerprints Become Even More Important in Automation

In small environments, administrators often manually accept host keys.

In larger DevOps environments, that approach becomes dangerous.

You may have:

Ansible
GitHub Actions
GitLab CI
Jenkins
Terraform provisioners
deployment scripts
backup servers
monitoring systems

connecting to servers automatically.

Blindly disabling host verification using:

-o StrictHostKeyChecking=no

may make automation easier, but it removes an important security check.

A better approach is to manage trusted host keys intentionally.

For example:

ssh-keyscan server.example.com >> ~/.ssh/known_hosts

But even ssh-keyscan should not automatically be considered proof of identity.

If an attacker is intercepting the network at the moment you run it, you may simply record the attacker’s key.

The safest approach is to obtain the expected fingerprint through an independent trusted channel.

The Security Idea Behind the Fingerprint

The important idea is simple:

Encryption protects the conversation.
Authentication proves who you are talking to.

SSH provides both.

Your connection may be strongly encrypted, but if you encrypt a conversation with an attacker instead of your server, encryption has not solved the identity problem.

The host key and its fingerprint solve that part.

A Simple Mental Model

Think about SSH like meeting someone at an airport.

They tell you:

I am the person you came to meet.

You could simply believe them.

Or you could ask for identification.

The SSH host key is the identification.

The fingerprint is the easy-to-check summary printed on the ID.

Once you verify the person once, you remember what they look like.

That is essentially what:

~/.ssh/known_hosts

does.

Commands Worth Remembering

Check your public key fingerprint:

ssh-keygen -lf ~/.ssh/id_ed25519.pub

Check the server’s ED25519 fingerprint:

sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Remove an outdated host entry:

ssh-keygen -R server.example.com

Inspect your stored known hosts:

cat ~/.ssh/known_hosts

Scan a server’s published SSH host key:

ssh-keyscan server.example.com

Easy Way to Remember It

Remember:

Fingerprint = identity, known_hosts = memory.

SSH asks:

Who is this server?

The fingerprint answers:

This is its identity.

Then known_hosts says:

I have seen this identity before.

If the identity suddenly changes, SSH warns you.

That simple model explains most of SSH host key verification.

Final Thought

SSH is considered secure partly because it does not silently trust every server you connect to.

That strange-looking SHA256 string during your first connection is SSH giving you an opportunity to verify the machine’s identity.

Most administrators encounter SSH fingerprints every day.

Far fewer actually verify them.

And that is the important difference.

The next time SSH asks:

Are you sure you want to continue connecting?

do not think of it as an annoying prompt blocking your login.

Think of it as SSH asking one very important question:

“Are you sure this is really your server?”

It's like a PULL and PUSH button on the door, but how, lets findout.

For a long time, I understood APIs.

At least, I thought I did.

One application needs data from another application.

It sends a request.

The other application sends a response.

Simple.

Then I started working with systems where one service needed to react immediately when something happened somewhere else.

A payment completed.

A GitHub push happened.

A new order arrived.

A trading signal appeared.

A deployment finished.

My first instinct was always the same:

Call the API.

And that is exactly where the problem starts.

Because sometimes the biggest difference between a good integration and a terrible one comes down to one question:

Who should start the conversation?

That question explains almost everything about APIs and webhooks.

Imagine You Are Waiting for a Package

Suppose you ordered a new laptop.

There are two ways to find out whether it has arrived.

The first method is to call the delivery company every five minutes.

“Has my package arrived?”

They say no.

Five minutes later:

“Has my package arrived?”

No.

Again.

And again.

Eventually:

“Yes, it arrived.”

Technically, this works.

But it is obviously inefficient.

This is basically what happens when you repeatedly call an API to check whether something has changed.

It is called polling.

Now imagine another approach.

You give the delivery company your phone number and say:

“Call me when the package arrives.”

You stop checking.

You continue doing your work.

When the package arrives, they contact you automatically.

That is basically a webhook.

And once I understood it this way, the difference became much easier to remember.

API Means: “I Need Something From You”

With an API, your application usually starts the communication.

Your application sends a request.

The remote system sends back a response.

For example:

My App
   |
   | GET /users/42
   v
API Server
   |
   | User data
   v
My App

You ask:

GET /api/orders/123

The API responds:

{
  "id": 123,
  "status": "paid"
}

The important part is this:

Your application asked first.

That makes APIs perfect when you need information or want to perform an action.

For example:

POST /api/users

Create a user.

GET /api/products

Get products.

DELETE /api/server/42

Delete a resource.

The client controls when the communication happens.

Webhook Means: “Tell Me When Something Happens”

A webhook reverses that relationship.

Instead of your application constantly asking:

Did something happen?

Did something happen?

Did something happen?

You provide another application with an endpoint.

For example:

https://myapp.com/webhooks/payment

Then you say:

“Whenever a payment succeeds, send the event here.”

Later, when a payment actually succeeds:

Payment Provider
       |
       | POST payment event
       v
https://myapp.com/webhooks/payment

The payload might look like this:

{
  "event": "payment.completed",
  "payment_id": "pay_98372",
  "amount": 100,
  "currency": "USD"
}

Your application did not ask for this information at that moment.

The external service sent it because an event occurred.

That is the core idea.

APIs are usually request-driven.

Webhooks are event-driven.

The Mistake Many Developers Make

Imagine your application needs to know when someone pays an invoice.

One solution is:

while True:
    status = check_payment_status()

    if status == "paid":
        process_payment()

    time.sleep(10)

This means your application calls the payment API every 10 seconds.

Let us say the customer takes 20 minutes to pay.

That means:

20 minutes
= 1200 seconds

1200 / 10
= 120 API requests

119 of those requests might simply return:

not paid

Then the 120th request finally returns:

paid

Now imagine thousands of customers.

Suddenly your infrastructure is generating enormous amounts of traffic just asking:

“Anything changed?”

This is why webhooks are so powerful.

Instead of checking 120 times, the payment provider sends exactly one request when the payment happens.

API Polling

The flow looks like this:

Your App ---> API: Anything new?
Your App ---> API: Anything new?
Your App ---> API: Anything new?
Your App ---> API: Anything new?
Your App ---> API: Anything new?
API ---> Your App: Yes, payment completed.

Your application is constantly pulling information.

Webhook

With a webhook:

Your App ---> Payment Service:
Notify me at /webhook/payment
time passes...
Payment Service ---> Your App:
Payment completed.

Much cleaner.

Much faster.

Much less unnecessary traffic.

But Here Is Something Important

People often compare:

Webhook vs API

as if you must choose one.

That is slightly misleading.

In many real systems, you use both.

For example, imagine Stripe tells your server:

payment.completed

through a webhook.

Your application might then call Stripe’s API:

GET /payments/pay_98372

to retrieve additional information.

So the architecture becomes:

Stripe
   |
   | Webhook
   v
Your Backend
   |
   | API request
   v
Stripe API
   |
   | Full payment details
   v
Your Backend

The webhook tells you:

“Something happened.”

The API lets you ask:

“Give me more information about what happened.”

That combination is extremely common.

A Real DevOps Example: GitHub

Imagine you have a CI/CD system.

You want a deployment to start every time someone pushes code.

You could continuously call the GitHub API:

Any new commits?
Any new commits?
Any new commits?
Any new commits?

That would be terrible.

Instead, GitHub sends a webhook when someone pushes:

Developer
    |
    | git push
    v
GitHub
    |
    | Webhook
    v
CI/CD Server
    |
    | Build
    | Test
    | Deploy
    v
Production

The entire automation becomes event-driven.

This idea powers a huge part of modern DevOps.

GitHub Actions.

Jenkins.

Argo CD.

CI/CD pipelines.

Slack integrations.

Monitoring alerts.

Payment systems.

Automation platforms.

They all rely heavily on events.

Another Example: Trading Systems

Suppose a trading application needs to react when a signal appears.

One architecture is polling:

Trading Bot
    |
    | API request
    v
Signal Server

"Any signal?"

Five seconds later:

"Any signal?"

Again:

"Any signal?"

Instead, the signal provider can send:

POST /webhook/signal

with:

{
  "symbol": "BTCUSDT",
  "action": "BUY",
  "price": 112500
}

Now the flow becomes:

Signal Generator
       |
       | Webhook
       v
Trading Backend
       |
       | API request
       v
Exchange
       |
       v
Order Created

This is where webhooks become very powerful.

They connect event-driven systems.

So Which One Is Faster?

Usually, webhook-based event notification is faster.

With polling every 60 seconds, an event might occur right after your last poll.

That means your application might wait almost 60 seconds before discovering it.

With webhooks, the provider can notify you almost immediately.

So instead of:

Event happens
wait...
        wait...
        wait...
Next API poll
Event discovered

you get:

Event happens
      |
      v
Webhook sent
      |
      v
Application reacts

This is why webhooks are common in real-time automation.

But Webhooks Are Not Automatically Better

Webhooks introduce their own problems.

Your webhook endpoint must be reachable.

For example:

https://api.example.com/webhooks/github

The external service needs to access it.

Your endpoint also needs to handle failures.

Imagine:

Stripe ---> Your Server
500 Internal Server Error

What happens now?

A good webhook provider will retry.

Maybe after:

10 seconds
1 minute
5 minutes
30 minutes

This means your application must also be prepared to receive the same webhook more than once.

Which leads to one of the most important webhook concepts.

Webhooks Must Be Idempotent

Imagine a payment webhook arrives twice:

payment.completed
payment.completed

If your code does this:

create_order()
send_product()

twice, you might accidentally create two orders.

Instead, you usually store the event ID.

For example:

{
  "event_id": "evt_12345"
}

Before processing it:

if event_already_processed(event_id):
    return
process_event()
mark_as_processed(event_id)

Now duplicate deliveries are safe.

This concept is called idempotency.

It is incredibly important when building webhook systems.

Then Comes Security

Here is another mistake beginners make.

They create:

POST /webhook/payment

and trust anything sent to it.

That means anyone on the internet might send:

{
  "event": "payment.completed",
  "amount": 100000
}

Your application must verify that the webhook actually came from the real provider.

Most platforms solve this using cryptographic signatures.

For example:

Webhook Payload
+
Secret Key
+
Signature

Your server calculates the expected signature and compares it with the incoming one.

If they match:

Accept webhook

If not:

Reject request

This is why you often see headers such as:

X-Hub-Signature
Stripe-Signature
X-Webhook-Signature

Never blindly trust webhook payloads.

API Authentication and Webhook Authentication Are Different

With APIs, your application normally proves its identity to the server.

For example:

Authorization: Bearer API_KEY

The conversation looks like:

Your App ---> API
            "Here is my token."

With webhooks, the opposite side often needs to prove the event came from them.

Webhook Provider ---> Your App
                     "Here is my signature."

That difference is worth remembering.

REST API vs Webhook

Another common confusion is thinking webhook means some completely different protocol.

Usually, it does not.

A webhook often uses normal HTTP.

For example:

POST /webhooks/order
Content-Type: application/json

So technically, a webhook endpoint may itself be an HTTP API endpoint.

The difference is mainly how and why it gets called.

With a normal API:

You decide when to send the request.

With a webhook:

An external event decides when the request is sent.

A Simple Comparison

FeatureAPIWebhookWho starts communication?ClientEvent providerTypical modelRequest/responseEvent notificationReal-timeDepends on pollingUsually near real-timeTrafficCan be high with pollingUsually lowerBest forQuerying and actionsNotificationsDirectionYou call themThey call youPublic endpoint neededNot necessarilyUsually yesRetry handlingUsually client controlledProvider controlledDuplicate handlingLess commonVery important

When Should You Use an API?

Use an API when your application needs to request something.

Examples:

Get user details
Create a VM
Start a deployment
Check inventory
Create an order
Update a database record
Get monitoring metrics

Your application knows exactly when it needs the information.

When Should You Use a Webhook?

Use a webhook when your application needs to react to something.

Examples:

Payment completed
GitHub code pushed
Customer registered
Order shipped
Server alert triggered
Build finished
Message received
Trading signal generated

The external system knows when the event happens.

So let it tell you.

The Architecture Pattern I Now Look For

Whenever I design an integration, I ask:

Do I need information right now?

Use an API.

Or:

Do I need to know when something happens?

Use a webhook.

And sometimes the answer is:

Both.

For example:

Customer pays
      |
      v
Payment Provider
      |
      | webhook
      v
Your Application
      |
      | API request
      v
Payment Provider
      |
      | details
      v
Your Application
      |
      v
Database
      |
      v
Email / Notification / Shipping

This is one of the most common patterns in modern distributed systems.

The Bigger Lesson Is Not About Webhooks

The bigger lesson is about architecture.

Traditional systems often think like this:

Check.
Check.
Check.
Check.
Check.

Modern event-driven systems think like this:

Something happened.

React.

That small shift changes everything.

It reduces unnecessary requests.

It improves response time.

It makes automation easier.

It allows systems to become more loosely coupled.

And once you start recognizing this pattern, you see it everywhere.

GitHub push events.

Stripe payment events.

Slack messages.

Cloud events.

CI/CD pipelines.

Server monitoring.

Trading signals.

IoT devices.

Kafka streams.

Message queues.

Serverless functions.

Modern infrastructure is increasingly built around events.

The Easiest Way to Remember It

I use this mental shortcut:

API = Ask

Webhook = Tell

API:

“Give me the latest order.”

Webhook:

“Tell me when a new order arrives.”

Or even shorter:

API     → I call you.
Webhook → You call me.

That one sentence explains most of the difference.

And once you understand that, webhooks stop looking like another complicated backend concept.

They become something much simpler:

A way for one system to say to another system:

“Don’t keep asking me. I’ll tell you when something happens.”

Your Docker Image Tag Is Lying to You

For years, this looked completely normal to me:

services:
  api:
    image: mycompany/api:v1.4.2

Version v1.4.2.

Clear. Predictable. Safe.

Or at least that is what it looks like.

Then you spend enough time working with Docker, CI/CD pipelines, Kubernetes, registries, and production systems, and eventually you discover something slightly uncomfortable:

A Docker tag does not actually identify an image permanently.

It is just a pointer.

And pointers can move.

That is where Docker digests enter the story.

Imagine This Production Deployment

Suppose our CI pipeline builds an application:

docker build -t registry.example.com/payment-api:v2.3.0 .
docker push registry.example.com/payment-api:v2.3.0

We test it.

Everything passes.

We deploy:

image: registry.example.com/payment-api:v2.3.0

Perfect.

A week later somebody rebuilds the image and pushes it using the same tag:

docker push registry.example.com/payment-api:v2.3.0

Now the registry contains a different image behind the same tag.

The deployment configuration still says:

v2.3.0

Nothing appears to have changed.

But the actual container image may have changed completely.

That is the important distinction.

Docker Tags Are Names

Most of us interact with Docker images through tags:

nginx:latest
nginx:1.27
postgres:16
myapp:production
myapp:v2.4.1

The basic structure is:

repository:tag

For example:

nginx:1.27

Here:

nginx

is the repository, while:

1.27

is the tag.

Tags are extremely useful because humans can understand them.

Compare:

payment-api:v2.3.0

with:

payment-api@sha256:7d83f4ab32c917f...

I know which one I would rather type.

But there is a trade-off.

Tags are mutable.

A registry can allow another image to be pushed using the same tag.

Think of a Docker tag like a DNS name.

You visit:

example.com

but the IP address behind it can change.

Similarly:

myapp:v1

is a convenient name pointing toward some image.

The image behind it can potentially change.

Docker Digests Are Identities

Docker also identifies images using content digests.

They normally look like this:

sha256:2f7c5d8a4e6b...

You can reference an image like this:

nginx@sha256:abcdef123456...

Instead of:

nginx:1.27

The major difference is that the digest is based on the image content.

If the image changes, the digest changes.

So:

myapp@sha256:AAA

and:

myapp@sha256:BBB

cannot silently become the same artifact.

That makes a digest extremely useful for reproducible deployments.

Tag vs Digest

The easiest mental model I use is this:

Tag     = Name
Digest  = Identity

Or:

Tag     -> What humans call the image
Digest  -> What Docker proves the image is

Consider Git.

A Docker tag is somewhat similar to a Git branch:

main

Today main might point to:

abc123

Tomorrow it might point to:

def456

The name stayed the same.

The code changed.

A Docker digest is more like a Git commit hash.

abc123

That commit identifies a specific state.

This analogy made Docker digests much easier for me to remember.

The Most Dangerous Tag

You can probably guess it.

latest

I still see production configurations such as:

services:
  backend:
    image: company/backend:latest

It feels convenient.

But what exactly is latest?

Version 2?

Version 5?

Yesterday’s build?

Today’s build?

The last successful build?

The build pushed by someone’s laptop ten minutes ago?

The answer is simply:

Whatever image the registry currently associates with that tag.

latest does not magically mean stable.

It is just a tag named latest.

Even Version Tags Can Move

A common response is:

I don’t use latest. I use semantic versions.

For example:

myapp:v1.7.3

Much better.

But there is still an important detail.

Unless the registry prevents it, somebody can push another image using:

v1.7.3

again.

Now:

v1.7.3

points somewhere else.

This is why mature container registries often support immutable tags.

Once:

v1.7.3

is published, the registry refuses to let someone overwrite it.

That gives you much stronger guarantees.

But digest pinning provides an additional level of certainty.

Finding a Docker Image Digest

Pull an image:

docker pull nginx:1.27

Then inspect it:

docker image inspect nginx:1.27

Or:

docker image inspect nginx:1.27 \
  --format='{{json .RepoDigests}}'

You may get something similar to:

[
  "nginx@sha256:abc123..."
]

Now instead of deploying:

nginx:1.27

you could deploy:

nginx@sha256:abc123...

That deployment now points to a specific artifact.

Docker Compose With a Digest

Instead of:

services:
  web:
    image: nginx:1.27

you can write:

services:
  web:
    image: nginx@sha256:abc123...

Now another push to:

nginx:1.27

does not change what your deployment uses.

Your Compose configuration references the exact image.

Kubernetes Makes This Even More Important

Suppose your Kubernetes Deployment contains:

containers:
  - name: api
    image: registry.example.com/api:production

The tag:

production

might move every time your CI pipeline runs.

That can make debugging painful.

Imagine three nodes pulling the image at different times.

Operationally, you want to be able to answer:

Exactly which artifact is running in production?

Not:

Probably whatever production pointed to when this pod started.

A stronger deployment specification looks like:

containers:
  - name: api
    image: registry.example.com/api@sha256:abc123...

Now there is no ambiguity.

What I Prefer in CI/CD

I do not think tags are bad.

Actually, I want both.

A good CI/CD pipeline can produce:

myapp:2.8.4
myapp:git-a8f61d2
myapp@sha256:7ae9...

Each serves a purpose.

The semantic version is understandable:

2.8.4

The Git SHA gives traceability:

git-a8f61d2

And the digest provides artifact identity:

sha256:7ae9...

A pipeline might build:

docker build \
  -t registry.example.com/myapp:${VERSION} \
  -t registry.example.com/myapp:${GIT_SHA} \
  .

Then push both:

docker push registry.example.com/myapp:${VERSION}
docker push registry.example.com/myapp:${GIT_SHA}

After the push, obtain the digest.

Your deployment system can then promote the exact digest that passed testing.

This changes an important part of the release process.

Instead of:

Build production image

you aim for:

Build once
        ↓
Test artifact
        ↓
Promote same artifact
        ↓
Deploy exact artifact

That is a much stronger model.

Build Once, Deploy Many

This is one of the principles I care about most in DevOps.

Imagine this pipeline:

DEV
 ↓
build image

STAGING
 ↓
rebuild image

PRODUCTION
 ↓
rebuild image

Those are technically three different builds.

Even if they use the same source code.

Dependencies could change.

Base images could change.

Package repositories could change.

Build scripts could behave differently.

Instead I prefer:

Build
  ↓
Image Digest ABC
  ↓
Dev
  ↓
Staging
  ↓
Production

The exact artifact moves through environments.

That means the container running in production is literally the artifact that survived your previous validation stages.

This is where digest-based deployment becomes extremely powerful.

Rollbacks Become More Predictable

Suppose release A has:

sha256:111

and release B has:

sha256:222

You deploy B.

Something goes wrong.

Rollback becomes:

sha256:222
        ↓
sha256:111

There is no question about what version the old tag currently points toward.

You already know the exact artifact.

This is particularly useful during incidents where the last thing you want is ambiguity.

Digests Also Matter for Supply Chain Security

Container security is no longer just:

Is this image vulnerable?

Another important question is:

Is this actually the artifact we approved?

Suppose your security pipeline scans:

myapp:v4

Everything passes.

Later someone replaces the image behind:

myapp:v4

If production only references that tag, the artifact you deploy may no longer be the artifact you scanned.

With digest-based promotion you can establish a stronger chain:

Build
   ↓
sha256:ABC
   ↓
Scan ABC
   ↓
Sign ABC
   ↓
Approve ABC
   ↓
Deploy ABC

Now security checks follow the artifact itself rather than merely its friendly name.

This becomes even more useful with tools such as:

Cosign
Sigstore
SBOM generation
Trivy
Grype
Admission controllers

The digest becomes the anchor connecting those controls.

So Should We Stop Using Tags?

No.

That would make working with Docker unnecessarily painful.

Tags are excellent for humans.

I still want:

v2.5.0

instead of having conversations like:

Can you deploy sha256:74072e995c3cf...

The better approach is:

Humans discuss tags.
Machines deploy digests.

For example, your release dashboard may show:

Release: v2.5.0
Commit:  8fa8c21
Image:   sha256:92af...

The developer sees:

v2.5.0

The DevOps pipeline sees:

sha256:92af...

Everybody wins.

A Production-Friendly Strategy

For systems I manage, a strong container release model looks something like this:

Developer pushes code
        ↓
CI builds Docker image
        ↓
Tag with semantic version
        ↓
Tag with Git SHA
        ↓
Push to registry
        ↓
Capture image digest
        ↓
Run vulnerability scan
        ↓
Run integration tests
        ↓
Sign/approve artifact
        ↓
Deploy exact digest

For example:

payment-api:3.4.1
payment-api:8a721fe
payment-api@sha256:2839...

The first is useful for people.

The second connects the container to Git.

The third tells infrastructure exactly what should run.

One Small Docker Detail, Huge Operational Difference

Docker tags feel like versions.

But technically they are references.

Docker digests are what identify the actual artifact.

That distinction becomes increasingly important as your infrastructure grows from:

docker run

to:

Docker Compose
Kubernetes
GitOps
Argo CD
Flux
CI/CD pipelines
multiple environments
multiple clusters
software supply-chain controls

At small scale, deploying:

myapp:latest

might feel perfectly fine.

At production scale, you eventually want to know:

What exact code is running?
What exact image was tested?
What exact artifact was scanned?
What exact artifact should we roll back to?

Docker digests give you much stronger answers to those questions.

So the mental model I now keep is extremely simple:

Tags tell me what we call the release.

Digests tell infrastructure what the release actually is.

And when production is involved, that difference matters.

Tags are for humans. Digests are for certainty.

AI Coding Is Moving From Prompt Engineering to Context Engineering. intent.md Might Be More Important Than Your Next 1,000-Line Prompt

A few days ago, I thought I had finally figured out how to work properly with AI coding agents.

I had learned about CLAUDE.md.

And it felt like a superpower.

Instead of repeatedly telling Claude:

“Use this architecture.”

“Do not touch this folder.”

“Run these tests.”

“Follow this coding style.”

“Use Docker for local development.”

I could put all of that information inside one file.

Claude could read it.

The project suddenly had memory.

I thought:

This is it.

This must be how serious developers use AI coding agents.

Then I discovered something that completely changed how I think about AI-assisted development.

CLAUDE.md is only one layer.

There can also be:

intent.md

spec.md

plan.md

architecture.md

tasks.md

decisions.md

And suddenly I realized something important.

We may be moving toward a world where developers do not only write code.

We also write context for machines.

The Problem With AI Coding Is Usually Not the AI

Imagine giving a very talented engineer access to your repository.

But you tell them almost nothing.

You say:

“Build the authentication system.”

That engineer now has dozens of questions.

What authentication method?

JWT?

Sessions?

OAuth?

Who are the users?

What database?

What security requirements?

What happens when the token expires?

Should refresh tokens exist?

Should there be MFA?

What should the API response look like?

An AI coding agent has exactly the same problem.

And yet this is how many of us use AI.

We give the agent one sentence.

Then we become surprised when it makes assumptions.

The agent writes technically correct code.

But it solves the wrong problem.

This is where structured context files become incredibly powerful.

CLAUDE.md Tells the Agent How to Work

Think of CLAUDE.md as the project's operating manual.

It can contain information such as:

Use Python 3.12.

Use FastAPI for APIs.

Use PostgreSQL.

Use pytest for tests.

Never modify database migrations manually.

Run tests before completing a task.

Use Docker Compose for local development.

This is extremely useful.

But notice something.

These instructions describe how the agent should behave.

They do not necessarily explain why the project exists.

That is where things become more interesting.

intent.md Explains Why We Are Building Something

Imagine a project contains this:

# Intent
We are building a simple deployment platform for small development teams.
The goal is to allow a developer to connect a Git repository and deploy an application without manually managing servers.
The product should feel simpler than Kubernetes.
Users should not need infrastructure knowledge.

This tiny file changes everything.

Now the AI understands the direction of the product.

If the agent needs to choose between:

A complex Kubernetes architecture

or

A simple Docker-based deployment system

the intent helps guide the decision.

Without intent, the AI might ask:

“What is technically possible?”

With intent, it can ask:

“What best matches the product we are trying to build?”

That is a huge difference.

spec.md Explains What Must Actually Exist

Now imagine another file.

# Authentication Specification

Users must be able to:
- register with email and password
- verify their email
- log in
- request password reset
- refresh access tokens
Access tokens expire after 15 minutes.
Refresh tokens expire after 30 days.
Passwords must be hashed using Argon2.
The API must return JSON responses.

Now the AI does not have to invent requirements.

The requirements already exist.

This reduces one of the biggest problems with AI coding:

guessing.

A good specification turns an AI coding agent from:

“something that generates code”

into:

“something that implements decisions.”

plan.md Can Tell the Agent How to Get There

Then you can go even further.

# Implementation Plan

1. Create user database model
2. Add password hashing
3. Add registration endpoint
4. Add login endpoint
5. Add JWT generation
6. Add refresh token support
7. Add password reset
8. Add tests
9. Update API documentation

Now something interesting happens.

The AI no longer needs to solve the whole problem in one giant prompt.

It can work through a sequence.

This matters because large AI coding tasks often fail for the same reason large human projects fail.

Too much ambiguity.

Too many decisions.

Too much happening at once.

A plan reduces the search space.

This Starts Looking Less Like Prompt Engineering

And more like software engineering.

That was the part that surprised me.

For a long time, AI coding conversations looked like this:

Me:
Build feature X.

AI:
Here is some code.

Then prompt engineering became popular.

People started writing longer prompts.

Then system prompts.

Then repository instructions.

But structured files like:

CLAUDE.md
intent.md
spec.md
plan.md
architecture.md
tasks.md

feel like the next step.

We are no longer writing one giant prompt.

We are creating a machine-readable development environment.

A Simple Mental Model

Here is how I now think about these files.

CLAUDE.md

How should you work?

Coding rules, commands, conventions, constraints.

intent.md

Why are we building this?

Business goals, user goals, philosophy, product direction.

spec.md

What exactly should be built?

Requirements and expected behavior.

plan.md

How will we build it?

Implementation sequence.

architecture.md

How is the system designed?

Services, databases, queues, APIs, boundaries.

tasks.md

What should be done next?

Concrete pieces of work.

decisions.md

Why did we choose this approach?

Important architectural decisions and trade-offs.

Imagine an AI Agent Entering This Repository

It opens the project.

It reads:

CLAUDE.md

Now it knows how to behave.

Then:

intent.md

Now it understands the purpose.

Then:

spec.md

Now it understands the requirements.

Then:

architecture.md

Now it understands the system.

Then:

plan.md

Now it understands the execution strategy.

At that point, the agent is no longer entering the project blind.

It has something surprisingly close to what a new engineer receives during good onboarding.

And that may be the real breakthrough.

AI Agents Need Onboarding Too

Companies spend days onboarding engineers.

Here is the architecture.

Here are our standards.

Here is why we built the system this way.

Here is what the product is trying to achieve.

Here are the current priorities.

Here are the things you must never break.

But when we open an AI coding agent, we often give it none of that.

Then we expect senior-engineer-level decisions.

That is probably unrealistic.

Maybe the future of AI development is not about finding the perfect prompt.

Maybe it is about building the perfect context environment.

Context Is Becoming Part of the Codebase

This is the part I find fascinating.

Repositories traditionally contain:

source code
tests
configuration
documentation
CI/CD
infrastructure

Now they may increasingly contain another layer:

AI context

Files written specifically to help intelligent agents understand the project.

That means documentation is no longer only for humans.

It becomes part of the execution environment.

A missing specification might soon be almost as important as a missing configuration file.

The Developers Who Win With AI May Not Be the Best Prompters

They may be the people who are best at defining:

• intent
• constraints
• architecture
• specifications
• plans
• acceptance criteria

Because once those things are clear, AI can generate a surprising amount of the implementation.

This changes the developer’s role.

Instead of spending all day telling the computer:

how to write every line

we may spend more time telling it:

what the system should become.

The Repository of the Future Might Look Like This

project/
│
├── CLAUDE.md
├── intent.md
├── spec.md
├── architecture.md
├── plan.md
├── tasks.md
│
├── src/
├── tests/
├── infrastructure/
└── docker-compose.yml

The code is still there.

But the instructions surrounding the code become much richer.

The AI can understand the project before touching it.

And This Is Where Things Get Really Interesting

Imagine multiple AI agents.

One reads the specification.

One designs the architecture.

One implements the backend.

One writes tests.

One reviews security.

One updates documentation.

All of them reading the same shared context.

At that point, these Markdown files are not just documentation anymore.

They are almost like an API between humans and AI agents.

Humans define intent.

Agents transform intent into software.

My Biggest Realization

When I first learned about CLAUDE.md, I thought:

“Great. Now Claude understands my coding rules.”

After learning about intent.md, spec.md, and similar files, my thinking changed.

Now I think the bigger idea is:

AI coding agents need structured context just like human engineers need good documentation.

The better the context, the less the agent guesses.

The less it guesses, the better the implementation.

And that means the next generation of great developers may become extremely good at something we previously underestimated.

Writing clear instructions about what software should be.

Not just writing the software itself.

That is a very different skill.

And I have a feeling it is going to become one of the most important engineering skills of the AI era.

I Thought CLAUDE.md Was Enough. Then I discovered intent.md, spec.md and plan.md was originally published in Dev Genius on Medium, where people are continuing the conversation by highlighting and responding to this story.