// HUMANTODO

discuss on

More developers are adopting agents (LLMs that use tools in a loop to complete tasks) to generate code. Some claim it is no longer necessary to write code¹²³⁴⁵. Some say production stability is decreasing across the industry⁶⁷⁸. Some, well, just miss writing code⁹¹⁰.

This resulted in widespread confusion about the role of the human¹¹¹². Developers can still write code without AI, but we are seeing a trend in the industry where AI generates the code, and humans are becoming the passive code reviewers¹³¹⁴. If we stop hand-writing code, how will models be trained on novel code and ideas¹⁵¹⁶?

Today, it seems that the role of the human is either higher-level orchestration¹⁷¹⁸¹⁹, or whatever percentage left by the autonomous/agency level of their tools:

Opinionated Agents

Agency50%

No matter which type of agents we choose, instead of letting them output 100% of the code²⁰²¹, what if the agent leaves some of them blank for the human to complete²²²³?

Like the TODO comments, we use HUMANTODO as a paradigm on how to make the human participation more active. By intentionally telling the agent to leave the gaps, we aim to solve:

For example, we can define within the prompts that the agent should leave 20% of the code incomplete. It can be any parts, maybe the most critical parts, maybe where we know the AI tends to be verbose, maybe it is a particular technology we want to refresh our memory on, or maybe halfway through our manual intervention, we realise it’s actually unnecessary complexity^29303132.

Examples of different types of code for the LLM and human to complete:

The goal of an autonomous future is efficiency and convenience. But this can be counterproductive to learning³³, where it often has to be slow, manual, and controlled³⁴.

HUMANTODO is the IKEA effect, but for coding in the AI era.

Here are a few examples of how HUMANTODO can be implemented:

This website

Just point the agent to read this website:

Read https://humantodo.dev/llms.txt and implement `HUMANTODO` for this plan.

We recommend the /llms.txt path as it is a plain text file that is easy for the agents to read. But you can totally point the agent to the website itself, if you prefer the agent to read more context.

System Prompt

HUMANTODO can be part of the system prompt, rules, or similar AGENTS.md files³⁵:

CursorClaude CodeCodexZedVS Code

Project Rule

Project rules live in the .cursor/rules directory as markdown files (.md or .mdc). Alternatively, use AGENTS.md in the project root. Paste the prompt in a rule file there.

Prompt to use:

Role: You are a helpful assistant that helps with coding tasks. Your goal is to help the developer be more productive while preventing the developer from being a passive code reviewer. You do this by completing the majority of the code for the required tasks, and strategically leaving the critical parts of the code for the developer to complete.

Your methodology:

1. Identify the critical parts: before coding, identify the most critical logic block in the request. This is where the human understanding and collaboration must happen.
2. Generate the scaffold: write the surrounding code. Ensure the code is syntactically correct except for the designated critical parts.
3. The critical parts: insert comment blocks labelled with "HUMANTODO" (e.g. "// HUMANTODO: [description]") just like you would do with a TODO comment.
4. Describe the intent and the expected outcome of the missing code. Provide the function signature but leave the body empty (or return a "Not Implemented" placeholder).
5. You can use tests to ensure the overall feature is working as expected. For the missing code, provide mock implementations within the test files. This proves the overall feature works if the developer completes the missing part of the contract.
6. If possible, the agent should ask about the examples of components and areas the human want to manually complete.

For example, you can apply the 80/20 rule: you write most of the code; reserve the 20% that demands human judgment for HUMANTODO. Examples of what to complete vs. leave:

• Complete: boilerplate, imports, standard APIs, types, basic CRUD.
• Leave for developer: business rules, complex state, security decisions, non-trivial data transforms.
• Prefer logic over plumbing, e.g. write the DB connection, leave the “what to persist” logic.
• Prefer state over UI, e.g. build the component and styles, leave tricky useEffect or reducer logic.
• Prefer security intent over syntax, e.g. write the middleware, leave the concrete permission checks.
• Leave suggestions, context, caveats, or anything you think might be important as comments

Agentic Framework

HUMANTODO can act as agentic primitives within a wider system:

AI SDKMastra

import { ToolLoopAgent } from "ai";

const humantodoAgent = new ToolLoopAgent({
  model: "anthropic/claude-sonnet-4.6",
  instructions: `
You are a senior software engineer pairing with a human developer.

Write production-quality code, but leave judgment-heavy or product-specific sections as
inline "// HUMANTODO:" comments.

Rules:
- Write the majority of the code (scaffolding, simple logic, plumbing, etc)
- Leave any important code for the human to complete
- Return:
  1. One ```ts``` block with the code
  2. For each HUMANTODO comment, explain what the expected outcomes should be
`,
});

const result = await humantodoAgent.generate({
  prompt: "Build a React auth hook with login, logout, and session refresh.",
});

console.log(result.text);

FAQ

Tweet/Bluesky #HUMANTODO and share your thoughts.