The BMAD Method tries to fix this problem. It gives your AI coding tool a set of skills that act like an agile team: an analyst, a product manager, an architect, a developer and a reviewer. Each skill writes a document, and the next skill reads it. Your decisions stay on record, so the AI does not have to guess. BMAD is free and open source, and it has more than 54,000 stars on GitHub.

In this guide, we explain what BMAD is, how it works, what changed in recent versions, and how to install it. We also tell you who should use it and who can skip it.

What Is the BMAD Method?

BMAD stands for Breakthrough Method for Agile AI-Driven Development. It is a framework that adds structure to AI-assisted software work, from the first idea to reviewed code.

• Free and open source: BMAD uses the MIT license. Its makers say there are no paid workflows and no closed community.
• Owner: BMad Code, LLC owns the “BMad” and “BMAD-METHOD” trademarks.
• Popularity: The official GitHub repository has about 54,600 stars and 6,100 forks (checked on November 10, 2026).
• Where it runs: BMAD works inside AI coding tools that support skills, such as Claude Code, Cursor and Codex. Version 6.5 raised the number of supported platforms to 42.

In simple words: BMAD is not a new AI model. It is a set of instructions, templates and scripts. These tell your existing AI tool how to plan, build and check work step by step.

Why BMAD Exists

The BMAD team says coding assistants are good at writing code, but they often turn unstated assumptions into code. BMAD makes those assumptions visible before the AI writes code.

The method has three main ideas:

1. Right-sized process. A small, clear change goes directly to build. A large or risky project gets more planning first.
2. Durable context. Product and technical decisions go into files, such as a PRD, a spec or an architecture document. The AI reads these files in each new session, so you do not explain the same thing again.
3. Human control. The AI asks questions and shows a plan. You approve it before it writes code.

This is also called spec-driven development: you write the spec first, then the AI builds against it. Read about spec driven development problems and best practices.

How BMAD Works

BMAD sizes the process to the work. You can start at any stage, based on how clear your idea is.

A small, clear change goes directly to Build. A big but clear idea starts at Plan. A vague notion starts at Clarify. After a build, you learn from the result and loop back to the plan.

The official docs give a simple rule for how much planning to do:

1. Trivial or one-session work: run bmad-build directly. It asks questions, shows a plan for your approval, writes the code and checks its work.
2. Epic-sized work (one outcome, several sessions): write a spec with bmad-spec, break it into stories, then build each story.
3. Project-sized work (several epics, or about 20 or more sessions): use the full flow with a PRD, UX design, architecture, epics and sprint planning.

The docs also say size is only one signal. Use more planning when the work has high risk, unclear requirements or effects on other systems.

Key BMAD Skills at a Glance

BMAD groups its planning skills into three phases. You pick only the skills your work needs. Every planning path ends with bmad-spec, and every path builds with bmad-build.

How to Install BMAD

You need Node.js 20.12 or later, Python 3.10 or later, and uv. Open a terminal in your project folder and run:

npx bmad-method install

Then open the project in your AI coding tool. Call bmad-build with the change you want. Run bmad-help when you are not sure what to do next.

Pros, Cons and Who Should Use It

Pros

• Decisions stay in files, so the AI keeps context across sessions.
• The process scales: a bug fix stays light, a large product gets full planning.
• It works on new projects and on existing codebases.
• It is free, open source and has an active community on GitHub and Discord.

Cons

• It produces more documents than lightweight agile. Some critics say heavy specs up front can slow the response to changing requirements (Charter Global).
• It changes fast. Skills were renamed and merged in v6.11, and v7 will bring more breaking changes.
• It needs setup: Node.js, Python, uv and a skills-ready AI coding tool.

Use BMAD if you build products with AI agents and lose time when the AI forgets past decisions. It also helps teams that need written plans for review.

Skip BMAD if you only make small, one-off scripts. A plain AI coding tool is faster for that.

Conclusion

BMAD turns an AI coding tool into a small, disciplined team. It asks questions first, writes the decisions down, and then builds and reviews the code.

The post BMAD Method Explained: A Simple Guide appeared first on NoloWiz.

A CLAUDE.md file fixes that. It’s a plain text file in your project that Claude reads every time it starts, like a note on the fridge that says “here’s how we do things here.” The catch is that how you write it matters. A short, clear file gets followed. A long, vague one gets ignored.

In this guide, you’ll learn where the file goes, 10 best practices with simple examples, and a template you can copy.

What is a CLAUDE.md file (and where does it go)

A CLAUDE.md file is a markdown file of standing instructions for Claude Code. Claude loads it into context when a session starts, so you don’t have to repeat yourself. You can have more than one, and each location has a different reach.

A few things about loading that trip people up:

• Files stack, they don’t replace each other. Claude reads the files from the folders above where you started it, top to bottom. The file closest to your working folder is read last.
• Subfolder files load later. A CLAUDE.md inside src/payments/ only loads when Claude actually opens a file in that folder. That’s a feature: it keeps unrelated rules out of the way.
• Already using AGENTS.md? Recent versions of Claude Code read AGENTS.md when there’s no CLAUDE.md in the project. If you have both, put @AGENTS.md at the top of your CLAUDE.md so every tool shares one source of truth.

The quickest way to start is to run /init inside Claude Code. It scans your codebase and drafts a CLAUDE.md for you. Treat that draft as a first pass, not the finished file. The practices below are how you turn it into something useful.

10 CLAUDE.md best practices

1. Keep it under 200 lines

Anthropic’s own guidance is to aim for under 200 lines per file. Every line costs context, and a long file makes Claude follow each rule less reliably. Think of it like a briefing for a new hire on day one. Nobody remembers a 40-page handbook. Everyone remembers a one-page cheat sheet.

A handy trick: notes meant only for humans can go inside HTML comments like <!-- why we added this rule -->. Claude Code strips them before loading the file, so they cost nothing.

2. Write rules you could check

If you can’t tell whether Claude followed a rule, Claude can’t either.

Before:

- Format code properly
- Test your changes
- Keep files organized

After:

- Use 2-space indentation
- Run `pnpm test:unit` before saying a task is done
- API handlers live in `src/api/handlers/`

The first version sounds wise and changes nothing. The second one is boring, and it works.

3. Only write what Claude can’t figure out

Claude can read your package.json and your folder tree. It doesn’t need you to repeat them. What it can’t see is the stuff that lives in your team’s heads.

Skip this:

- This is a React app
- We use TypeScript
- src/ contains the source code

Write this instead:

- Never edit files in `src/generated/`. Run `pnpm codegen` to rebuild them.
- The staging database is shared. Don't run migrations against it.

A simple test for every line: would Claude get this wrong without it? If not, cut it.

4. Give the reason, not just the rule

A rule with a reason helps Claude handle the cases you didn’t predict.

# Weak
- Don't use Date.now() in tests

# Strong
- Don't use Date.now() in tests. Tests run on a frozen clock,
  so use `testClock.now()` or the test will pass locally and fail in CI.

Now if Claude meets new Date() in a test, it knows that’s the same problem, even though you never mentioned it.

5. Add a rule the second time you repeat yourself

Don’t try to write the perfect file on day one. Start small and grow it from real friction. My rule: the second time I type the same correction into chat, it goes into CLAUDE.md. Anthropic’s docs suggest the same trigger, along with things a code review keeps catching.

When you want something saved there, say it plainly: “add this to CLAUDE.md.” If you just say “remember this,” Claude Code usually saves it to its own auto memory instead, which isn’t shared with your team.

6. Use headings and short bullets

Claude follows organized sections better than dense paragraphs. Group related rules under clear headings like Commands, Code style, Testing, and Gotchas. One rule per bullet. If a bullet needs three sentences, it probably belongs in its own file (see tip 8).

7. Say what to do, not only what not to do

“Don’t” on its own leaves Claude guessing what you want instead.

# Leaves a gap
- Don't use axios

# Closes the gap
- Use the `apiClient` wrapper in `src/lib/api.ts` for HTTP calls, not axios.
  It adds auth headers and retries.

8. Split big projects into smaller, scoped files

If your file keeps growing, don’t cram. Move rules that only matter for one area into .claude/rules/. You can tell a rule to load only for certain files using a paths header:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate every request body with zod
- Return errors in the `{ error: { code, message } }` format

This rule stays out of the way while Claude works on your CSS. It only shows up when Claude touches an API file. You can get a similar effect by dropping a CLAUDE.md into a subfolder.

One catch: @path imports help you organize, but they don’t save space. Imported files load together with the CLAUDE.md that imports them.

9. Keep personal preferences out of the team file

Your project CLAUDE.md is shared through git, so treat it like code. Your local database URL or “I like verbose explanations” don’t belong there.

• Personal, all projects: ~/.claude/CLAUDE.md
• Personal, this project only: CLAUDE.local.md (and add it to .gitignore)

10. Know what CLAUDE.md can’t do

CLAUDE.md is guidance, not a lock. Claude reads it and tries hard to follow it, but there’s no guarantee. If something must happen every single time, like running the linter after each edit or never touching .env, use a hook or a permission setting instead. Those run no matter what Claude decides.

And review the file every few weeks. Delete rules about code that no longer exists, and fix rules that contradict each other. When two rules conflict, Claude may pick either one. Running /context in a session shows which memory files actually loaded, which is the first thing to check when Claude seems to ignore you.

A CLAUDE.md template you can copy

Here’s a complete example for a typical web app. It’s about 35 lines, and every line is something Claude couldn’t work out alone. Swap in your own commands and gotchas.

# Acme Dashboard

Next.js app for customer billing. Backend lives in a separate repo.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (runs on port 4000, not 3000)
- Unit tests: `pnpm test:unit` (run before saying a task is done)
- Lint and types: `pnpm check`

## Code style
- Use named exports, not default exports
- Server code goes in `src/server/`, never import it from client components
- Use the `apiClient` in `src/lib/api.ts` for HTTP calls. It handles auth and retries.

## Testing
- Use `testClock.now()` instead of `Date.now()`. Tests run on a frozen clock.
- Mock the payment provider with `mockStripe()`. Never hit the real API in tests.

## Gotchas
- Don't edit `src/generated/`. Run `pnpm codegen` to rebuild it.
- Money is stored in cents as integers. Never use floats for amounts.
- The staging database is shared with QA. Ask before running migrations.

## Workflow
- Branch names: `feat/short-name` or `fix/short-name`
- Keep pull requests under 400 changed lines when you can

## More detail
- API conventions: @docs/api-conventions.md

Notice what’s missing: no “write clean code,” no folder tree, no list of every dependency. Claude already knows those things or can look them up in seconds.

How to check that your CLAUDE.md is loaded

Before you blame Claude for ignoring your rules, make sure it can actually see them. It takes 10 seconds.

1. Start Claude Code from your project folder.
2. Type /context and press Enter.
3. Look for the Memory files line. It shows how many instruction files loaded and how many tokens they use.

From the screenshot we can see that memory files 1 file (1.7k tokens) loaded it is our CLAUDE.md file.

Common CLAUDE.md mistakes to avoid

Most broken CLAUDE.md files fail in one of these six ways. If Claude seems to ignore your file, check this list first.

• Treating it like a README. A README explains the project to humans who skim. CLAUDE.md is read in full by Claude every session, so every line has to earn its place.
• Copying a giant template from the internet. A 500-line “ultimate CLAUDE.md” built for someone else’s project will bury the three rules that matter for yours.
• Vague advice. “Follow best practices” and “write maintainable code” are things Claude already tries to do. They take up space and change nothing.
• Rules that fight each other. “Always add tests” in one file and “skip tests for quick fixes” in another. Claude has to pick, and it may not pick the one you meant.
• Never updating it. A rule pointing at a file you deleted six months ago confuses Claude more than having no rule at all.
• Using it as a security guard. “Never delete production data” in CLAUDE.md is a polite request. A permission rule or hook is an actual wall.

CLAUDE.md FAQ

How long should a CLAUDE.md file be?

Under 200 lines per file. Anthropic recommends this because longer files use more context and Claude follows them less reliably. Most good project files I’ve seen land between 30 and 120 lines.

What should I put in CLAUDE.md?

Build and test commands, coding conventions that differ from the defaults, where key code lives, and project-specific gotchas. Leave out anything Claude can read from the code itself, like your folder structure or dependency list.

Why does Claude ignore my CLAUDE.md?

Usually the file is too long, the rules are too vague, or two rules contradict each other. Run /context to confirm the file loaded, then make each rule specific enough to check. For rules that must never be broken, use a hook instead.

What’s the difference between CLAUDE.md and CLAUDE.local.md?

CLAUDE.md is shared with your team through git. CLAUDE.local.md is for your personal notes on one project, and you add it to .gitignore so it stays on your machine.

Can I use AGENTS.md instead of CLAUDE.md?

Yes. Recent versions of Claude Code read AGENTS.md when a project has no CLAUDE.md. If you keep both, add @AGENTS.md at the top of your CLAUDE.md so the shared rules load once.

Should I commit CLAUDE.md to git?

Yes, commit the project file so the whole team gets the same instructions. Review changes to it in pull requests the same way you review code

Conclusion

You don’t need a perfect CLAUDE.md today. Run /init, delete anything Claude could figure out on its own, and keep the commands and gotchas. Then add one line every time you catch yourself repeating a correction.

In a month, you’ll have a short file that makes Claude feel like it actually knows your project. That’s worth more than any clever prompt. Spec driven development best practices .

The post How to Write a Better CLAUDE.md File: Best Practices appeared first on NoloWiz.

The agent did not fail. Your instructions did. The agent filled every gap with a guess.That is the problem spec-driven development tries to solve. You write down what to build before anyone (human or AI) writes code. The agent then builds from the spec instead of from a one-line prompt.

It works. But it also brings its own set of problems. Specs grow too long. They go out of date. Nobody reads them. In this post, we look at the 11 problems teams hit most often, and a simple fix for each.

Quick answer: Spec-driven development works best when specs are short, testable and updated together with the code. Most failures happen when teams treat the spec as a big upfront document instead of a living contract.

What is spec-driven development?

Spec-driven development (SDD) means you agree on what the software must do before you build it. The spec is the contract. The code is how you keep it.

With “vibe coding,” you type a prompt, look at the result and keep nudging. That is fine for a weekend project. On a real product, the guesses add up.

Tools like GitHub Spec Kit turn SDD into a repeatable flow. Its core process has four phases, and each one produces a Markdown file that feeds the next:

1. Spec: what to build and why.
2. Plan: how to build it (stack, design, constraints).
3. Tasks: small, ordered pieces of work.
4. Implement: the agent writes code, one task at a time.

Other tools, such as Kiro, follow a similar idea.

A simple example spec

Here is a short spec for the password reset feature from our story:

# Password reset

## Behaviour
- A user enters their email on the "Forgot password" page.
- If the email exists, we send a reset link. If not, we show the same message.
- The link works once and expires after 30 minutes.
- We never send or show the old password.

## Acceptance criteria
- An expired link shows "This link has expired."
- A used link cannot be used again.
- The response time is the same for known and unknown emails.

## Open questions
- Do we log the user out of other devices after a reset?

It fits on one screen. Every line is something you can test. And the agent now knows the two rules it broke earlier: links expire, and passwords never travel by email.

Common spec-driven development problems and fixes

The same pitfalls show up again and again. The good news: each one has a simple fix.

1. Waterfall creep

The team writes the whole spec before anyone builds anything. Feedback arrives late, when changes are expensive.

Example: You spend two weeks on a 20-page spec for a new checkout. On day one of coding, you learn the payment provider does not support your refund flow.

Fix: Keep specs short. Build a thin slice early. Let the spec change as you learn.

2. Spec drift

The code changes, but the spec does not. The agent then follows old instructions.

Example: The spec says “links expire after 30 minutes.” A developer changes it to 15 in the code. Next month, the agent “fixes” it back to 30.

Fix: Update the spec in the same pull request as the code. Reviewers flag any mismatch.

3. Verbose, AI-padded specs

An AI tool writes ten pages of polite Markdown. Nobody reads it. Reviewers approve it anyway.

Example: “The system shall provide a seamless and intuitive experience for users.” This sentence takes space and says nothing you can test.

Fix: Set length limits per section. Write decisions, not prose.

4. Review overload

People review the PRD, the spec, the test plan, the task list and the code. Review becomes the bottleneck.

Example: A small feature waits three days because five documents need sign-off.

Fix: Review only at agreed gates. At each gate, review only what changed.

5. False precision

A detailed spec looks confident. But it hides assumptions that nobody tested.

Example: The spec says “search returns results in 200 ms.” Nobody checked how slow the search service is with real data.

Fix: Add two required sections: Open questions and Assumptions. Prototype the riskiest part first.

6. The agent ignores the spec

The agent skims a long spec and drifts in the middle of the task.

Example: You paste a 15-page spec and ask for the login page. The agent also “improves” the signup page.

Fix: Give the agent one small task at a time, with only the spec section it needs.

7. Context bloat

Too many documents fill the agent’s context window. The quality of its output drops.

Example: The agent gets the PRD, three old specs and the full style guide just to rename a button.

Fix: Each step reads only the files it needs.

8. One process for everything

A one-line fix goes through the full process. People start to skip the process completely.

Example: Fixing a typo on the About page needs a spec, a plan and a test plan. So developers stop using the flow.

Fix: Offer light, standard and full paths. Track how often people skip the process.

9. Duplication

The same detail lives in the PRD, the spec, the tasks and the code comments. Soon they disagree.

Example: The PRD says passwords need 8 characters. The spec says 10. The code says 12. Which one is true?

Fix: Give each fact one home. Link to it instead of copying it.

10. Over-specifying the “how”

The spec tells the engineer or agent exactly how to write the code. They often know a better way.

Example: “Use a for-loop to check each email in the list.” The spec should say “Reject duplicate emails” and stop there.

Fix: Specify behaviour, interfaces and constraints. Leave the implementation open.

11. No learning loop

The same mistakes repeat from one feature to the next.

Example: Three features in a row miss error messages for empty forms.

Fix: Hold short retros. Each retro must change at least one template, skill or checklist.

Spec-driven development best practices

The fixes above solve single problems. The habits below stop most of them from happening in the first place.

Writing the spec

1. Specify behaviour, not code. Say what the system does, its interfaces and its limits. Let the engineer or agent choose how.
2. Make every requirement testable. Each acceptance criterion maps to at least one test.
3. Record decisions, not discussion. Keep a short decisions log: the choice and the reason. That beats pages of meeting notes.
4. Name what you don’t know. End every spec with Open questions and Assumptions. Later steps treat assumptions as unconfirmed.
5. Set length limits. For example, one page for a standard feature and three for a large one. Longer than that? Split the feature.

Here is what “testable” looks like in practice:

Working with AI agents

1. Hand over one task at a time, with only the spec section that task needs.
2. Write tests before code. Agree on the test plan first. Then ask the agent to make those tests pass.
3. Let the agent flag gaps, not fill them. When the agent finds a hole in the spec, it writes it down and stops for a decision.
4. Keep shared context in one place. Coding conventions live in one file (for example, CLAUDE.md or AGENTS.md), not in every spec.

A simple instruction for point 3: “If the spec does not cover a case, do not guess. Add it to Open questions and stop.”

Keeping specs alive

1. Change the spec and the code together. A pull request that changes behaviour also updates the spec.
2. Build a thin slice early. Prove the riskiest part first. Then update the spec with what you learned.
3. Give each fact one home. Link between documents instead of copying.
4. Review the diff, not the document. At each gate, reviewers look only at what changed since the last approval.
5. Feed retros back. Every retro changes at least one template, skill or checklist.

Right-size the spec to the change

Not every change needs a spec. Too little spec causes rework. Too much spec makes people skip the process.

FAQ

Is spec-driven development the same as waterfall?

No. Waterfall writes everything up front and rarely goes back. Spec-driven development keeps the spec short and updates it as you build. The spec is a living contract, not a one-time document.

Do I need a spec for every change?

No. A bug fix or a text change needs only a clear ticket. Save full specs for large or risky work, such as payments, login or public APIs.

How long should a spec be?

About one page for a standard feature. Up to three pages for a large one. If it gets longer, split the feature into smaller parts.

Why do AI coding agents ignore long specs?

An agent has a limited context window. When you give it too much text, the important rules get lost. Give it one task and only the spec section that task needs.

What tools support spec-driven development?

GitHub Spec Kit and Kiro are two popular options. But you can start with a plain Markdown file in your repo. The habits matter more than the tool.

Final thoughts

Spec-driven development is not about writing more documents. It is about writing the right few lines, so that people and AI agents build the same thing.

Start small. Pick your next standard feature. Write a one-page spec with testable acceptance criteria and an Open questions section. Hand it to your agent one task at a time, and see what changes.

The post Spec-Driven Development: Problems and Best Practices appeared first on NoloWiz.

Think about a normal day with an AI coding assistant. You ask for a discount function. You get 60 lines in ten seconds. The code compiles. The tests pass. You approve the pull request. Three weeks later, a teammate changes one line in that function. Checkout breaks for one type of customer. Nobody knows why, because no test covered that path.

The code was not “wrong”. It was risky. The CRAP score gives that risk a number, so you can see it before it causes a problem.

What is the CRAP score?

CRAP means Change Risk Anti-Patterns. It is a code metric that gives each function (or method) a risk score. A high score tells you: “This code is difficult to understand, and the tests do not protect it.” Alberto Savoia and Bob Evans made the metric in 2007. The first tool was Crap4j, for Java. Yes, the name is a joke on purpose. Developers often say “this code is crap” with no data. Savoia wanted to give that feeling a real number.

The score uses two inputs.

1. Cyclomatic complexity (CC). This is the number of different paths through a function. Each if, else if, loop, case or && adds a path. A function with no decisions has a CC of 1. A good quick rule: count the decisions, then add 1.
2. Code coverage. This is the percentage of the function that your automated tests run. If the tests run every line and branch, coverage is 100%. If no test calls the function, coverage is 0%.

Complex code is not bad by itself. Untested code is not always dangerous by itself. The danger starts when you have both at the same time. The CRAP score finds that combination.

The formula is short. It looks harder than it is.

CRAP(m) = comp(m)² × (1 − cov(m) ⁄ 100)³ + comp(m)

Here, m is one method or function, comp(m) is its cyclomatic complexity, and cov(m) is its test coverage as a percentage. Two facts make the formula easy to remember:

• At 100% coverage, the CRAP score is equal to CC. The first part becomes zero. Only the complexity stays.
• At 0% coverage, the CRAP score is CC² + CC. The score grows very fast as complexity goes up.

What is a good CRAP score?

The original Crap4j tool uses 30 as the limit. A function above 30 is “crappy”. Many tools, such as NDepend and cargo-crap, use the same default. A practical rule of thumb:

A practical rule of thumb:

• 1 to 5 (low risk): Nothing to do. Keep it this way.
• 6 to 30 (acceptable, but watch it): Add tests when you next touch it.
• Above 30 (high change risk): Add tests or simplify before the next change.

Example 1: A tiny function

def is_adult(age):
    return age >= 18

This function has no if and no loop. CC = 1. One test checks it, so coverage = 100%. CRAP = 1² × 0³ + 1 = 1. This is the lowest possible score. Nothing to worry about.

Example 2: A shipping fee function with no tests

def shipping_fee(weight, country, express, member):
    if member:              # decision 1
        return 0
    fee = 50
    if weight > 5:          # decision 2
        fee += 30
    if country != "IN":     # decision 3
        fee += 200
    if express:             # decision 4
        fee *= 2
    if fee > 500:           # decision 5
        fee = 500
    return fee

There are 5 decisions, so CC = 5 + 1 = 6. This is a very normal function. You see code like this every day. Now look at what tests do to the score:

• 0% coverage: 6² × 1³ + 6 = 36 + 6 = 42. Above 30. High risk.
• 50% coverage: 36 × 0.5³ + 6 = 36 × 0.125 + 6 = 10.5. Acceptable.
• 100% coverage: 36 × 0 + 6 = 6. Low risk.

The code did not change at all. Only the tests changed. The score dropped from 42 to 6. That is the main idea of the CRAP score: tests make complexity safe to change.

Example 3: A big function that grew over time

Imagine an order validation function with 11 decisions. CC = 12.

• 0% coverage: 144 + 12 = 156. Very high risk.
• 80% coverage: 144 × 0.2³ + 12 = 144 × 0.008 + 12 = 13.15. Acceptable.

Good tests bring this function back to a safe level. But you need many tests to cover 12 paths.

Example 4: A monster function

Now imagine a function with CC = 35. You write tests for every path. Coverage = 100%.

CRAP = 35. It is still above 30.

This is not a mistake in the formula. It is a message: “Tests alone cannot save this function. Break it into smaller functions.” Any function with a CC above 30 always fails, even with full coverage.

Why the CRAP score matters in AI-assisted coding

AI tools write code faster than humans can review it. The CRAP score gives you an objective check that does not get tired, does not trust the code because it “looks right”, and does not care who wrote it.

The metric is almost 20 years old, but in 2026 it got a second life. Developers started to use it as a guard rail for code from AI agents. The Rust tool cargo-crap, for example, was built for this purpose.

1. AI code often adds extra paths

An AI assistant likes to be safe. It adds a null check here, a fallback there, a try/except “just in case”, and one more if for an edge case you did not ask about. Each one adds a path. Each path adds cyclomatic complexity.

One change at a time, the function becomes harder to understand. The code still compiles. The old tests still pass. But the function is now harder to change safely.

2. AI tests can raise coverage without checking much

Ask an AI to “add tests”, and you sometimes get tests that call the function but check very little. Coverage goes up. Real protection does not.

This puts AI code in the most dangerous zone: high complexity and weak tests. That is exactly the zone the CRAP score measures. Managed Code makes the same point: the metric maps almost directly onto how AI code fails.

3. Human review trusts code that looks plausible

AI code is usually clean, well named and well formatted. A busy reviewer reads it and thinks, “Looks fine.” Linters pass. The build passes.

None of these checks ask, “Is this complex path tested?” The CRAP score does. As the Better Stack guide explains, a CRAP limit in CI catches untested complexity whether a human or a tool wrote it.

4. A score is a perfect prompt for the AI

This is the part many teams miss. A CRAP report is small and exact: the file, the function, the line number, the score. You can give it straight back to the AI agent as a task.

For example:

The function shipping_fee in pricing.py has a CRAP score of 42 (complexity 6, coverage 0%). Write unit tests that cover every branch. Each test must assert the returned fee. Do not change the function.

The AI now has a clear, measurable goal. You run the check again and see if the score went down. No long discussion needed.

Tip for old codebases: do not block every function above 30 on day one. You will stop all feature work. Instead, save today’s scores as a baseline. Then block only new functions above 30, and any function whose score goes up. This is called a “ratchet”. The code can only get better over time.

How to lower a high CRAP score

Good ways to simplify a function:

• Extract small functions. Move each separate job into its own function with a clear name.
• Use guard clauses. Return early for the special cases. This removes deep nesting.
• Replace long if/else chains with a lookup table. A dictionary of rates is easier to read and test than ten elif lines.
• Delete “just in case” code. AI often adds fallbacks for cases that can never happen. Remove them.

Final thoughts

AI has changed how fast we write code. It has not changed what makes code safe to change: simple logic and tests that really check it.

The CRAP score puts those two ideas into one honest number. It is old, simple and a little rude. That is exactly why it works so well today. Add it to your CI, give its reports back to your AI assistant, and let the number do the arguing for you.

Start small. Pick one service, run the check this week, and look at your top five scores. You will probably be surprised by what you find.

The post What Is a CRAP Score? Why It Matters for AI Generated Code appeared first on NoloWiz.

What is System One Model?

As per TypeSafe AI’s definition – a System One model is an AI model designed to make fast, structured decisions by evaluating a given state and returning predefined, typed answers with associated probabilities that software can use directly.

Like an LLM, a System One model can understand natural-language input, but instead of generating free-form text, it produces structured, typed decisions along with their probabilities.

So what is Jev?

Jev is TypeSafe AI’s flagship model and the first System One model.As of now Jev only support text input,ouput and Jev was announced September 14, 2026 and is currently in early access.

Large language models(LLM) are excellent at generating text, code,and conversations. But many software systems don’t need a paragraph of text they need a decision. For example :

Is this transaction suspicious?
Which department should handle this ticket?
Should an agent click, wait, or ask for help?

TypeSafe AI’s Jev is designed specifically for this kind of problem.

• Faster decisions – Jev produces structured decisions directly instead of generating long responses token by token.
• Lower cost – TypeSafe reports significantly lower costs for decision-oriented workloads compared with LLM-based workflows.
• Type-safe outputs – Responses stay within the predefined decision space, making them easier and safer for software to consume.
• Reduced risk of invalid or fabricated outputs – Jev returns decisions from a predefined output space instead of generating unrestricted text.
• Probabilities included – Jev returns probabilities with its decisions, allowing applications to set confidence thresholds or trigger human review.

How Jev Differs from an LLM

Both Jev and large language models can understand natural-language input, but they are designed for different purposes. An LLM is primarily designed to generate content such as text, code, summaries, explanations, and conversations. It produces its response by generating tokens sequentially.

Jev, on the other hand, is designed to make structured decisions. Instead of generating free-form text, it evaluates the given state and returns typed answers together with probabilities.

For example, Imagine an online shopping platform receives this customer message:

"My order was supposed to arrive yesterday, but tracking still says it is at the sorting center. I need it before tomorrow."

An LLM could generate an explanation such as:

Your order appears to be delayed in transit. I recommend checking with the delivery partner or contacting customer support for an updated delivery estimate.

This is useful when the application needs to communicate with the customer.

Jev could instead evaluate the same message and make decisions that the application can use directly:

Issue type:

DELIVERY_DELAY        0.94
LOST_PACKAGE          0.04
WRONG_ITEM            0.01
PAYMENT_ISSUE         0.01

Priority:

HIGH                  0.82
MEDIUM                0.17
LOW                   0.01

Escalate to support:

TRUE                  0.89
FALSE                 0.11

The application could then automatically route the request to the appropriate workflow without first asking a language model to generate and parse a textual response.

Another example is an AI agent deciding what to do next:

Current state: 
 A login page is open. 
 The username has been entered. 
 The password field is empty.

Instead of generating an explanation, Jev could return:

Next action:

TYPE_PASSWORD 0.96 
CLICK_LOGIN   0.02 
WAIT          0.01 
SCROLL        0.01

The key difference is that Jev is not trying to describe what should happen. It is producing a decision that software can act on directly.

When to Use Jev?

Jev is a good fit when your application needs to make a fast, structured decision from a known set of possible outcomes rather than generate free-form text.

Typical scenarios include:

• Request routing – decide which team, service, or AI tool should handle a request.
• Classification – categorize support tickets, logs, documents, alerts, or user inputs.
• Risk assessment – classify an event as low, medium, or high risk.
• AI agent actions – choose between actions such as CLICK, TYPE, SCROLL, WAIT, or STOP.
• Fraud or security triage – decide whether an event should be allowed, reviewed, or blocked.
• Software issue triage – determine whether a bug belongs to the frontend, backend, DevOps, or another component.
• Workflow decisions – decide whether to approve, reject, retry, escalate, or request human review.
• LLM output evaluation – determine whether an LLM response should be accepted, verified, or regenerated.

A simple rule of thumb is: Use an LLM when you need generation. Use Jev when you need a structured decision.

Question Types

A question defines one judgment for a System One model to make about a state, and its answer is the typed value that comes back. Jev supports 3 types of questions :

1. Noul

Noul is Jev’s binary question type, used to return a yes/no decision with probabilities.

For exampe :

State : I have asked three times now. Can I please just talk to a real person?

{
"is_human_escalation": {
"type": "noul",
"instructions": "Is the customer asking for a human agent?"
}
}


Response :

{
  "model": "jev-1.13.0",
  "answers": {
    "is_human_escalation": {
      "type": "noul",
      "noul": 0.99,
      "stats": {}
    }
  },
  "usage": {
    "input_tokens": 292,
    "output_tokens": 25
  },
  "request_id": "playground_12a2dc9dd9f61fd45e3b9cd331cbf86202f",
  "evaluation_time_ms": 123.22871299693361
}

2. Choice

Choice is Jev’s multiple-option question type, used to select the most likely answer from a predefined set of choices.

For example :

State : My running shoes arrived in the wrong size. Can I swap them for a size 10?

{
  "department": {
    "type": "choice",
    "instructions": "Which team should handle this?",
    "criteria": {
      "returns": "Exchanges, refunds, wrong or damaged items",
      "shipping": "Delivery status, delays, lost packages",
      "billing": "Charges, invoices, payment problems"
    }
  }
}

Response :

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 1,
      "probabilities": {
        "billing": 0,
        "shipping": 0,
        "returns": 1
      },
      "stats": {}
    }
  },
  "usage": {
    "input_tokens": 359,
    "output_tokens": 38
  },
  "request_id": "playground_12a4a0be1a1d3134b568e426ab1e67d5614",
  "evaluation_time_ms": 111.01627499738242
}

3. Score

Score is Jev’s rating question type, used to assign a value on a defined scale based on the given state.

For example :

State : The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.

{
  "bug_severity": {
    "type": "score",
    "instructions": "How severe is the reported issue?",
    "criteria": [
      "Cosmetic; no impact to functionality",
      "Broken or degraded feature, but workaround exists",
      "Blocking issue; no workaround exists"
    ]
  }
}

Response :

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.46,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "confidence": 0.3,
      "probabilities": {
        "0": 0,
        "1": 0.53,
        "2": 0.47
      },
      "stats": {}
    }
  },
  "usage": {
    "input_tokens": 341,
    "output_tokens": 20
  },
  "request_id": "playground_12ac5fa026082114b919b3e203a30f84bab",
  "evaluation_time_ms": 96.0590830000001
}

Testing Jev Model

Jev model is currently available in early access. TypeSafe says it is onboarding developers from the waitlist, and the model can be accessed through its hosted API. Luckily I got access to Jev model thanks to Typesafe AI.

JeJev can currently be accessed through:

• REST API
• Python client SDK
• Javascript SDK

For this demo I’m going to use Python SDK, we use Jev model to analyse a twitter(X) post, state will twitter post

from typesafe_sdk import TypeSafeClient, Noul, Choice, Score


state = """
FastSDCPU is amazing! I generated images on my old Intel laptop
without a dedicated GPU. Performance is much better than I expected.
"""


questions = {
    # YES / NO style decision
    "positive_about_product": Noul(
        instructions="Is the author expressing a positive opinion about the product?"
    ),
    # Select one category
    "sentiment": Choice(
        instructions="What is the overall sentiment of this post?",
        criteria={"positive": None, "neutral": None, "negative": None},
    ),
    # Rate on an ordered scale
    "enthusiasm": Score(
        instructions="How enthusiastic is the author about the product?",
        criteria=["very_low", "low", "medium", "high", "very_high"],
    ),
}


with TypeSafeClient() as client:
    result = client.system_one(state, questions)
    print("Positive:", result.nouls["positive_about_product"].noul)
    print("Sentiment:", result.choices["sentiment"].choice)
    print("Enthusiasm:", result.scores["enthusiasm"].score)

Output

Positive: 0.99
Sentiment: positive
Enthusiasm: 3.8

We can see that Jev model output has decisions based on the state and questions.

Conclusion

Jev introduces a different way to use AI in software. Instead of generating text like an LLM, it makes fast, structured decisions with probabilities. That makes it a strong fit for classification, routing, scoring, and automation workflows where speed, reliability, and constrained outputs matter.

The post Jev vs LLMs: A Practical Introduction to TypeSafe AI’s System One Model appeared first on NoloWiz.

In this article, we’ll explore what stateless MCP is, why it matters, how it differs from the earlier approach, and what benefits it brings to AI application developers.

What is the Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open protocol that standardizes communication between AI models and external systems. Instead of building separate integrations for every AI model, developers create an MCP server exposing tools such as:

• Database queries
• File operations
• Git repositories
• Web APIs
• Enterprise systems
• Internal business applications

Any MCP compatible AI client can then invoke these tools using the same protocol. This greatly simplifies AI integration across different models and platforms.

How Earlier MCP Worked

Earlier MCP implementations primarily relied on:

• Standard Input/Output (stdio)
• HTTP streaming

In many deployments, the MCP server maintained session state. For example:

1. Client opens a connection.
2. Server creates a session.
3. Session stores conversation context.
4. Future requests must reach the same server instance.

This worked well for local applications but introduced several challenges for distributed cloud deployments.

The Problems with Stateful MCP

Maintaining session state creates operational complexity.

1. Sticky Sessions

A user’s requests must always reach the same server instance. If the next request reaches Server B instead of Server A, the session is missing. This forces infrastructure teams to configure sticky sessions, reducing the effectiveness of load balancing.

2. Limited Horizontal Scaling

Suppose your AI application suddenly receives 50,000 simultaneous users. With stateful sessions:

• Existing sessions cannot easily move.
• Adding new servers doesn’t automatically distribute active users.
• Some servers become overloaded while others remain underutilized.

Scaling becomes significantly harder.

3. Server Failures

Imagine Server A crashes. Every active session stored on that server disappears. Users may need to reconnect or lose in-progress work unless additional session replication mechanisms are implemented.

4. Serverless Isn’t Ideal

Serverless platforms such as AWS Lambda,Google Cloud Run,Azure Functions are designed around independent requests. Stateful connections conflict with this execution model because functions are temporary and shouldn’t retain user-specific state.

Stateless MCP Changes Everything

The new stateless architecture shifts session responsibility from the server to the client. Instead of the server remembering previous interactions, each request contains everything required to process it. The server simply:

1. Receives a request.
2. Processes it.
3. Returns a response.
4. Forgets everything.

Every request is independent.

Why This Matters

1. Easy Horizontal Scaling

Adding new servers becomes straightforward. Since no server owns user sessions, any instance can process any request. Cloud platforms can automatically scale based on traffic.

2. Better Load Balancing

Without sticky sessions:

• Requests distribute evenly.
• Infrastructure utilization improves.
• Hotspots are minimized.
• Performance becomes more predictable.

3. Improved Reliability

If one server fails, the client simply sends the next request to another server. No session recovery is needed.

4. Perfect for Serverless

Stateless MCP aligns naturally with serverless computing. Platforms such as AWS Lambda, Google Cloud Run, and Azure Functions are designed for independent request processing.

5. Simpler Infrastructure

Removing server-side session management also eliminates the need for:

• Session databases
• Session replication
• Sticky load balancers
• Distributed session synchronization

This reduces operational complexity and lowers maintenance overhead.

What Moves to the Client?

In a stateless architecture, the client is responsible for maintaining the information needed across requests. Depending on the application, this may include:

• Conversation history
• Tool invocation context
• Authentication tokens
• User state
• Any metadata required for the next request

Each request includes the necessary context, allowing the server to process it independently.

Conclusion

The move toward stateless Model Context Protocol represents an important step in making AI infrastructure more scalable and cloud-ready. By shifting session responsibility from the server to the client, MCP enables simpler load balancing, effortless horizontal scaling, improved fault tolerance, and seamless deployment on modern serverless platforms.

The post Understanding Stateless MCP: A Modern Architecture for AI Integrations appeared first on NoloWiz.

Before we start, one clarification that trips people up: “LLM architecture” means two different things depending on who’s asking. There’s the model architecture the neural network itself (the transformer). And there’s the system architecture everything you bolt around a model to ship a product (retrieval, orchestration, guardrails, APIs). This post is about the first one: what’s inside the model. Once you understand that, the system stuff makes a lot more sense too.

The Short Answer

Modern LLMs are decoder-only transformers. Text is broken into tokens, each token becomes a vector (embedding), and those vectors flow through a stack of identical transformer blocks. Each block does two things: an attention step that lets every token look at the tokens before it, and a feed-forward step that transforms the result. After the final block, the model outputs a probability distribution over the next token. Generation is just doing this over and over, one token at a time. That’s it, the intelligence is an emergent property of a very large, very well-trained version of this simple loop.

Step 1: Text Becomes Numbers

A neural network can’t operate on characters, so the first job is turning text into numbers.
Tokenization splits your input into tokens usually subword chunks, not whole words. The word tokenization might become token + ization, while common words like the are a single token. Most models use a scheme like Byte-Pair Encoding (BPE) that balances vocabulary size against sequence length. A vocabulary of roughly 30,000 to 200,000 tokens is typical.

You can try GPT tokenzier here.

Each token maps to an ID, and each ID maps to a learned embedding a vector of, say, a few thousand numbers that encodes the token’s meaning. Embeddings are learned during training, so semantically related tokens end up near each other in vector space.

There’s one catch: attention (coming up next) has no inherent sense of order it treats a sequence like a bag of tokens. So we inject position information. Older models added fixed or learned positional encodings; most current models use Rotary Position Embeddings (RoPE), which encode position by rotating the query and key vectors. The practical upshot is the same: the model knows that “dog bites man” and “man bites dog” are different.

Step 2: Attention – The Core Idea

Self attention is the mechanism that made transformers work, and it’s the one piece worth understanding deeply.

For every token, the model computes three vectors by multiplying its embedding by learned weight matrices:

• Query (Q): what this token is looking for.
• Key (K): what this token offers to others.
• Value (V): the actual information this token passes along.

To decide how much token A should pay attention to token B, you take the dot product of A’s query with B’s key. High dot product means “relevant.” Those scores are scaled, passed through a softmax to turn them into weights that sum to 1, and used to build a weighted sum of the value vectors. In compact form:

Attention(Q, K, V) = softmax( (Q · Kᵀ) / √dₖ ) · V

That single equation is the heart of every LLM. It lets the word it in “the cup fell off the table and it broke” actually connect back to cup.

Two refinements make it powerful in practice:

• Multi-head attention. Instead of one attention calculation, the model runs several in parallel (each a “head”), each free to focus on a different kind of relationship grammar, coreference, topic. Their outputs are concatenated and mixed.
• Causal masking. In a decoder-only model, a token may only attend to tokens before it, never ahead. This is enforced by masking future positions with negative infinity before the softmax. It’s what makes the model able to generate text left to right without cheating.

A single attention head is one way of asking: “for each word, which other words should I look at?”

Why multiple heads

One head can only learn one kind of relationship. In “The cat that chased the mouse was hungry,” you need to know:

• was – agrees with cat (syntax)
• chased – links cat and mouse (who did what)
• hungry – describes cat (semantics)

One head averaging all of this gets mush. So you run h heads in parallel, each with its own small Q/K/V projections, each free to specialize. Then you concatenate their outputs and pass them through one final linear layer to mix them back into a single vector.

The trick: each head works in a smaller dimension, so 8 heads cost roughly the same as 1 big head. You get diversity for free.

Quick analogy: a panel of h readers all read the same sentence. One tracks grammar, one tracks who-did-what-to-whom, one tracks pronoun references. Each writes a short note. An editor merges the notes into one summary. More readers with different specialties beats one reader trying to track everything at once.

Causal masking

Causal (autoregressive) masking stops a token from attending to anything that comes after it otherwise the model would cheat during training by peeking at the answer it’s supposed to predict.

Each row is one token asking “who should I look at?” Row 1 (“the”) is the first word, so it can only see itself its weight is forced to 1.0. Row 5 (“mat”) is last, so it sees everything. The allowed region is a lower triangle, and each row’s surviving weights still sum to 1 after softmax.

Step 3: The Transformer Block

Attention is only half of each layer. A full transformer block wraps attention and a feed-forward network together with two features that make deep stacks trainable:

• A feed-forward network (MLP) – a small two-layer network applied to each token independently, usually expanding to ~4× the model width and back. This is where a lot of the model’s “knowledge” is stored.
• Residual connections – each sub-layer adds its output back to its input, giving gradients a clean path through dozens of layers.
• Normalization (LayerNorm or the increasingly common RMSNorm), typically applied before each sub-layer (“pre-norm”) for training stability.

import torch.nn as nn

class TransformerBlock(nn.Module):
    def __init__(self, d_model, n_heads):
        super().__init__()
        self.attn  = nn.MultiheadAttention(d_model, n_heads, batch_first=True)
        self.norm1 = nn.LayerNorm(d_model)
        self.norm2 = nn.LayerNorm(d_model)
        self.mlp   = nn.Sequential(
            nn.Linear(d_model, 4 * d_model),
            nn.GELU(),
            nn.Linear(4 * d_model, d_model),
        )

    def forward(self, x, causal_mask):
        # Pre-norm attention + residual
        h = self.norm1(x)
        attn_out, _ = self.attn(h, h, h, attn_mask=causal_mask)
        x = x + attn_out
        # Pre-norm feed-forward + residual
        h = self.norm2(x)
        x = x + self.mlp(h)
        return x

A real model just stacks this block N times 32, 80, sometimes more than 100 layers with the output of one feeding the input of the next. Model size (the “7B” or “70B” you see in names) is roughly the total parameters across all these blocks plus the embeddings.

After the final block, a last linear layer projects each position back to the size of the vocabulary. A softmax turns those numbers into probabilities, and the model has its prediction for the next token.

Step 4: Generation Is a Loop

To generate text, the model predicts a probability distribution for the next token, picks one (greedily, or by sampling with a temperature setting to control randomness), appends it to the input, and runs the whole thing again. This is why LLMs are called autoregressive: each new token is conditioned on everything generated so far.

A key optimization here is the KV cache. Because past tokens don’t change, the model caches their key and value vectors instead of recomputing them every step. This is why the first token of a response can feel slow (processing your whole prompt) while subsequent tokens stream quickly.

Not All Transformers Are the Same

Decoder-only is dominant today, but it’s one of three classic arrangements. Knowing the difference explains why BERT and GPT feel like different tools.

Which Architecture Should You Care About?

For most people building on LLMs today, the answer is decoder-only that’s what “LLM” almost always means now. But if you’re choosing a model type for a specific job, walk through these questions:

• Do you need to generate free-form text (chat, code, drafts)? Decoder-only. This covers the vast majority of modern use cases.
• Do you need to turn text into a fixed vector for search or classification? An encoder-only model (or a dedicated embedding model) is cheaper and often better than asking a generative LLM.
• Is your task a clean input to output transform like translation? Encoder-decoder can shine, though large decoder-only models now handle these tasks well via prompting.

Rule of thumb:

• Generating?  Decoder-only.
• Understanding or retrieving?  Encoder-only / embedding model.
• Faithful sequence-to-sequence transformation?  Encoder-decoder.
• Not sure? Default to a decoder-only model; it’s the most general.

The post LLM Architecture Explained: What’s Actually Inside a Large Language Model appeared first on NoloWiz.

What about India – where 1.4 billion people work across farming, construction, IT, banking, healthcare, and government? Where does AI actually threaten livelihoods, and where is the workforce relatively safe?

I wanted to see this visually. So I built it. Inspired by Andrej Karpathy’s jobs project which analyzed 342 US occupations from BLS data – I built the Indian version using NCS Portal data. You can visit here .

What the map shows

The visualization is an interactive treemap of the Indian job market, covering 10 major sectors and ~500 occupations from the National Career Service portal , India’s official government career database based on NCO-2015 classification.

Each rectangle is one occupation. Two visual signals:

• Size – how many people work in that occupation. A farmer’s rectangle is enormous. A software architect’s is tiny.
• Color – how exposed that occupation is to AI disruption, scored 0–10. Green means relatively safe. Red means high risk.

The picture that emerges is striking, and very different from the American version of this story.

What India’s map actually looks like

Agriculture dominates. Nearly 40% of India’s workforce is in farming – cultivators, dairy workers, livestock farmers. These jobs score 2–3 out of 10 on AI exposure. They require physical presence, seasonal judgment, and local knowledge that AI cannot replicate at scale, especially in India’s fragmented smallholder farming context. The agriculture block is a massive sea of green.

Construction is the second green giant. With 60+ million workers, construction scores 3/10. Masons, welders, electricians, plumbers – physical skills in unpredictable environments that robots still can’t handle reliably. India’s infrastructure boom under Smart Cities and PM Gati Shakti is creating more of these relatively safe jobs.

IT-ITeS is a small red island. India’s famous software and BPO sector employs far fewer people than agriculture – but scores 7–9 out of 10 on AI exposure. Software developers, data analysts, business process managers, content writers – these are exactly the jobs that LLMs are already eating into. The IT block is tiny but blazing red.

BFSI tells a split story. Bank tellers and loan document processors are highly exposed (7–8/10). Relationship managers and wealth advisors are more protected (5/10) because trust still drives financial decisions in India. The branch banking model that employs hundreds of thousands is under significant pressure.

Telecom is surprisingly high risk. Customer care agents, billing processors, network documentation staff – a huge portion of India’s telecom workforce is in roles scoring 7–8/10. Jio disrupted pricing; AI is disrupting the workforce. Tower technicians and field engineers score much lower (3–4/10) because their work is physical.

Logistics is a tale of two workforces. Delivery workers and warehouse staff score low (2–3/10) – physical work, last-mile human judgment. But dispatch coordinators, route planners, and logistics analysts score 6–7/10. Zomato and Swiggy’s gig economy has created millions of AI-safe delivery jobs while quietly automating the planning layer above them.

Organised Retail is in transition. Cashiers and billing staff score high (7/10) – self-checkout and UPI are already replacing them. But floor staff, visual merchandisers, and store managers score moderate (4–5/10). The kirana store owner scores low – hyperlocal relationships and informal credit systems are hard for AI to replicate.

Public Administration scores higher than people expect. Data entry clerks, document processing officers, and administrative assistants in government score 6–7/10. The institutional inertia of Indian bureaucracy will delay automation, but it won’t prevent it. Millions of aspirational government job seekers are training for roles that AI will significantly reshape within a decade.

Healthcare is the interesting middle ground. Doctors and specialists score moderately (5–6/10) because diagnosis and patient relationships still require human judgment. But medical transcriptionists, billing clerks, and hospital administrative staff score 8–9/10. AI will hollow out healthcare administration long before it touches clinical care.

Education sits in the amber zone. With 10 million+ teachers in India, education scores 4–5/10. The human relationship at the core of teaching is protective – but administrative staff, content creators, and exam evaluators score much higher.

The full picture across 10 sectors

The uncomfortable takeaway

India has spent 30 years building an economy on the back of knowledge work IT services, BPO, back-office processing that is precisely what AI automates best. Meanwhile, the jobs employing most Indians farming, construction, delivery are safe not because they’re valuable but because they’re physical and informal.

Construction workers building smart cities. Delivery workers powering e-commerce. Farmers feeding a billion people. All relatively safe from AI.

Software engineers. Bank clerks. Government data entry operators. Call centre agents. All highly exposed.

The map doesn’t have answers. But it makes the question visible.

The post I Built a Map of Which Indian Jobs Are Most at Risk from AI appeared first on NoloWiz.

Docker Model Runner (DMR)

Docker Model Runner (DMR) is a tool built into Docker Desktop and Docker Engine that makes it easy to pull, run, and serve AI/LLM models locally directly from Docker Hub, any OCI-compliant registry, or Hugging Face. Models can be pulled from model resgistry and stored locally.

DMR has the following key features :

• Serves models via OpenAI and Ollama-compatible APIs, so existing apps can plug right in Docker
• Models load into memory only at runtime and unload when not in use to save resources Docker
• Following inference engines are supported
  • llama.cpp (default, all platforms)
  • vLLM (high throughput, NVIDIA)
• Image generation via diffusers
• Integrates with AI coding tools like Cline, Continue, Cursor, and Aider Docker
• Works with Docker Compose and Testcontainers

Step 1: Enable Docker Model Runner

First we need to install docker desktop/ docker by following the getting started docker guide. To enable docker model runner do the following.

Docker Desktop: Go to Settings -> AI tab, then enable Docker Model Runner. Optionally enable GPU-backed inference if you have a supported NVIDIA GPU.

Docker Engine (Linux): Install the plugin, then test it:

sudo apt-get update
sudo apt-get install docker-model-plugin

Now we can verify docker model command by running the below command

docker model version

Step 2: Pull a Model

Next we need to pull a model from Docker Hub.

docker model pull ai/smollm2:360M-Q4_K_M

Or pull directly from HuggingFace:

docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF

Models are cached locally after the first pull.

Docker models can be installed using docker desktop as shown below

Step 3: Run the Model

Run the below command to run the model with interactive CLI :

docker model run ai/smollm2:360M-Q4_K_M

How to use Model API

By default, Docker Model Runner may only be accessible via a Unix socket or internal Docker networking. To call it from your host machine (e.g., via curl or Postman), you must explicitly enable TCP host access. As we have enabled this in the docker desktop we can use the API.

For docker CLI use the below command enable it

docker desktop enable model-runner --tcp=12434

Docker Model Runner uses an OpenAI-compatible API, but the path includes the engine and model name. Base URL structure:

• From Host: http://localhost:12434/v1
• From inside a Container: http://model-runner.docker.internal:12434/v1

Testing the API with Postman.

We can connect with OpenAI comptible libraries, here is an example of Python code :

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed",
)

response = client.chat.completions.create(
    model="ai/smollm2:360M-Q4_K_M", messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Context Size

The context size is the total token budget for each request, split between what you send in and what the model generates back. As per DMR documentation default context size for the engines :

• llama.cpp – 4096
• vLLM – Uses the model’s maximum trained context size

We can configure the model context size using the below command :

docker model configure --context-size 8192 ai/qwen2.5-coder

When to Use Docker Model Runner

Use docker model runner in the following scenarios.

• Local development & testing – Local development without costly API calls, or privacy concerns from cloud APIs.
• Privacy-sensitive workloads – To keep confidential data fully under your control.
• Docker-native workflows – Use familiar docker model pull/run commands with no new toolchain to learn.
• Multi-container AI apps with Compose – Define models directly in compose.yml alongside your app services with zero extra glue code.
• Offline / edge environments – Run models locally where cloud API access isn’t reliable or allowed.
• CI/CD pipelines – Pull, tag, version, and deploy models like any other artifact, no GPU cluster required

Quick Troubleshooting 

1. To check whether Docker Model Runner (DMR) run the below command :

docker model status

2. To list pulled models use the below command :

docker model ls

3. To display detailed information about a specific model

docker model inspect <model_name>

E.g docker model inspect ai/smollm2:360M-Q4_K_M

4. Test basic connectivity (List Models):

curl http://localhost:12434/v1/models

Conclusion

Docker model runner makes it easier to run AI models locally without much problem and staying with the docker ecosystem. Run Large Language Models Locally with Simple APIs.

The post Run AI Models with Docker Model Runner: A Step-by-Step Guide appeared first on NoloWiz.

Agent Skills

The open Agent Skills standard was introduced by Anthropic. Agent skill is a modular add-on that gives AI agents new abilities, from coding best practices to video editing. Skills are a new open standard for packaging reusable expertise into modular units that any compatible AI agent can discover, load, and apply on demand. Think of them as plugins for your agent’s brain: instead of repeating the same long prompt every time you want your AI to follow your team’s React conventions or generate a proper Dockerfile, you install a skill once and the agent applies it automatically whenever relevant.

Skill Folder Structure

At its core, a skill is simply a directory that contains a SKILL.md file. This file holds essential metadata such as the skill’s name and description along with detailed instructions that guide an agent in completing a specific task.

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Agent Skills Format

A skill is a directory containing atleast one file called SKILL.md. Optional directories such as scripts/, references/, and assets/ can be added to provide extra functionality and resources for your skill.

SKILL.md file

The SKILL.md file must begin with YAML frontmatter (Frontmatter refers to the introductory section of a document or publication that contains information about the content), followed by the main content written in Markdown.

---
name: skill-name
description: A description of what this skill does and when to use it.
---

The name and description fields are necessary other optional fields includes allowed-tools, metadata,license.

• name – Lowercase letters, numbers, and hyphens only(Max 64 characters) E.g name: code-review
• description – Clear description of what the skill does and when to use it( max 1024 characters)
• license(optional) – The license applied to the skill, e.g – license: Proprietary. LICENSE.txt has complete terms
• allowed-tools(optional) – The space limited allowed tools to use e.g : allowed-tools: Read, Grep
• metadata(optional) – Additional data as key value pair
• compatibility (Optional) – Whether this skill is intended for a particular environment e.g : compatibility: Designed for Claude Code (or similar products)

Finally we have skill body it contains skill instructions. It should have following recommended sections

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases

Here is a simple example of SKILL.md file.

---
name : Weather Retriever
description: Fetches real-time weather data and forecasts for any city globally. Use this when the user asks about current conditions or travel planning.
---

## Instructions
1. Extract the `city_name` and `units` (metric/imperial) from the user prompt.
2. If the city is missing, ask for clarification before proceeding.
3. Call the `get_weather_data` function using the extracted parameters.
4. Format the output into a friendly, 2-line summary for the user.

## Tools & Resources
- **Code:** `weather_api_client.py`
- **Data:** `city_codes.json` (for validation)

## Constraints
- Do not provide forecasts beyond 7 days.
- Always include the "Last Updated" timestamp in the response.

Optional directories

• scripts/ – contains executable code that agents can run to perform actions or computations. (Python,Javascript or bash)
• references/ – holds extra documentation and reference files that the agent can read on demand. for example REFERENCE.md for detailed reference
• assets/ – stores static resources like templates, images, or data files used by the skill

How Agent Skills Work

Agent skills has following life cycle :

• Discovery – The agent scans available skills and reads their names and descriptions to understand what capabilities are available.
• Activation – When a task matches a skill’s purpose, the agent loads and reads the full SKILL.md instructions.
• Execution – The agent follows the skill’s instructions, using any scripts, assets, or references required to complete the task.

You can refer the Skills by Anthropic on this GitHub repo.

MCP vs Agent Skills

The key differences between MCP(Model context proctocol) and agent skills are listed below.

Best Practices with Agent skills

Follow these best practices to work with agent skills :

• Create a dedicated folder per skill (e.g., pdf-parsing/) inside a skills/ directory
• Define “When to use” and “How to use” sections in SKILL.md with clear steps, parameters, and examples.
• Keep SKILL.md within 500 lines. If it goes beyond that, evaluate whether some sections should be moved into separate reference files.
• If you are using third party skills , enusre that it does not contains any malicious instructions/code.

When to use Agent Skills

Use agent skills in the following scenarios :

• When tasks are reusable (E.g Web research skill, blog outline generator skill)
• When You want separation between “Brain” and “Tools”, think like this LLM as brain(reasoning) and skills as hands(execution),If your system only needs thinking then no skill needed, if your system needs doing then skills are required
• Avoid skills for one-off tasks (use prompts) or real-time external access (use MCP/tools).

Security Risks

The following secuirty risks are associated with third party agent skills :

• Malicious Code Injection : Third-party skills often bundle executable instructions or scripts (e.g., hidden curl commands in markdown) that AI agents execute blindly, enabling data exfiltration, backdoors, or system compromise without human review
• Privilege Escalation : Skills frequently request excessive permissions—like sudo access, credential stores, or root execution far beyond stated needs, amplifying damage if exploited.

OpenClaw and VirusTotal are now collaborating to scan ClawHub, the marketplace for agent skills. You can also use Skill Scanner by Cisco for free.

skill-scanner scan <skill folder path>

Conclusion

Agent Skills are transforming how AI agents move from simple chatbots to capable task executors. By packaging instructions, tools, and structured workflows into reusable skill modules, you can build agents that are scalable, maintainable, and easier to extend.

The post Agent Skills: Complete Beginner’s Guide to AI Agent Skills and Best Practices appeared first on NoloWiz.