Module Structure
AI doesn't know about your school.
«Aniqlik so'rovda — aniqlik javobda»Ask Claude: what is “Mars Pro”? You'll get an answer about a planet or some software. Why doesn't AI know about your school? Because Mars IT School is niche/local. In this module — how to describe a task so that AI doesn't guess, and how to understand where it's guessing by default.
Hook — “Mars Pro”? AI thinks about a planet.AI o'qituvchining maktabini bilmaydi
You open claude. “Come up with 5 Python assignments for my 12-year-olds this week.” You get: sum of squares, primality test, FizzBuzz, guess the number, dictionary. Technically correct. For your kids — way off.
You ask: “what is Mars Pro?” AI confidently: “apparently, some professional software for a Martian mission…”. It doesn't know about your school plan.
Ask Claude: “what is Mars Pro?” — you'll get an answer about a planet. Why doesn't AI know about your school? For AI, Mars IT School = rare / niche / local. This isn't a model bug. It's a map of where it's strong and where it needs to be fed.
Three skills I'll be checking for
- Apply all 3 levels of Description — product (what I want) / process (how to think) / performance (how I'll know it's good) — all three explicitly in one prompt, not just one or two.
- Recognize whether a task falls into mainstream knowledge vs. niche/local; in the niche zone, reinforce the prompt with your own data (
@-mentionfiles,@-importin CLAUDE.md, MCP). - Apply the Description ↔ Discernment loop — 2-3 iterations of prompt refinement, not just one "perfect on the first try."
Mental model — what AI knows and how to tell it.AI nimani biladi va unga qanday tushuntirish
There are two layers here. Knowledge — what the model already has in its head from training. Description — how you package your task to make it retrieve and apply that knowledge. Let's break down both.
1. What AI knows well, and what it will invent
The model is strong where the material in its training appeared frequently, recently (before the cutoff date) and consistently across different sources. It's weak where it appeared rarely, after the cutoff, narrowly, locally (one city, one school) or where sources disagree with each other.
The practical question isn't "does AI know this?", but "how well was this represented in what it read?". A four-zone scale:
Obsolescence (true at training time ≠ true now), uneven coverage (narrow/local areas are weak), inherited bias (what was in the data is considered “normal”), source amnesia (“read it somewhere” — but it's not a quote). All four operate simultaneously. For a Mars mentor, uneven coverage and source amnesia are the first to hit.
2. Three Levels of Description — product · process · performance
Three layers of a good description: product — what should come out (format, audience, style). process — how the agent should think (steps, what to read first). performance — how you'll know it's good, and how it behaves (brief/detailed, argues/supports). All three — in one prompt, not just one or two.
What I want as output
Specific artifact. Format. Audience. Style. Length.
How you should think
Steps. Plan first. Which files to read. What to think about before answering.
How I'll know it's good
Verification criterion. Tone. What the AI should discard itself. When to say “I don't know”.
3. Description ↔ Discernment loop — the course engine
This isn't about “writing the perfect prompt on the first try”. It's a cycle: you describe → the agent acts → you evaluate each of the three layers (product/process/performance — what's wrong?) → you rewrite the description more precisely → repeat. 2-3 iterations are normal. One “perfect” prompt on the first attempt is rare luck.
Description
product · process
performance
AI output
model attempt
Discernment
evaluate on all 3 layers
Antipattern №1 in Mars: mentor writes one long prompt → gets the wrong thing → blames the model. Pattern: short prompt → you see what the AI did → you understand which layer was missing → you add it. After 2-3 rounds — a working template that you can then reuse.
Six Techniques prompting — from Anthropic Fluency.Oltita texnika — prompting uchun
Six techniques, each fitting into product / process / performance. Remember these six, and they'll cover 90% of your prompts.
Anthropic calls it a “secret weapon”: “Ask the AI itself to help improve your prompt.” Finished your prompt? Ask Claude: “What in this request is unclear to you?” Often a whole layer you hadn't considered pops out from there.
The same prompt “come up with 5 Python assignments for 12-year-olds” — is run through 4 iterations. On which version (V1, V2, V3, V4) — in your opinion — will the AI start to filter out weak options itself, without your push? Write down the number. Let's check.
Demo — four iterations of one prompt.Bitta prompt — to'rtta variant
Zuhra, a Python mentor from Yunusobod. Monday morning, she needs to prepare material for a group of 12-year-olds. The same basic request. Each version adds one Description layer. Mock-output shows what changes in quality.
V1 · bare — no layers
$ claude › come up with 5 Python assignments for 12-year-olds ⠋ Done: 1. Sum of squares from 1 to n 2. Check if a number is prime 3. FizzBuzz 4. Guess the number (random) 5. Count vowels in a string
What's wrong: technically valid, but it's a generic Hour-of-Code set. For which 12-year-olds exactly? Just started? Already know conditions? What's the topic — loops, strings, dictionaries? It's completely unclear how to evaluate these. Discernment signal: the prompt hit mainstream AI knowledge and pulled the most average from the training data.
V2 · +product — what I want as output
› come up with 5 Python assignments, topic for/while, for 12-year-olds, who already know if/else but have just started loops. Format: 1 sentence condition + 1 example input/output. ⠋ Done: 1. Print numbers from 1 to 10, each on a new line. Example: input — none, output — 1\n2\n...\n10 2. Calculate the sum of all even numbers from 1 to 20. Example: input — none, output — 110 3. Print the multiplication table for 5 (up to 5×10). 4. Until the user types "stop", repeat the greeting. 5. Find the first number starting from 1 whose square is greater than 100.
Better: now on topic (loops), now considers the level (they know if/else). But it's still abstract, like school. "Sum of evens" for a 12-year-old — why? What's a typical mistake? What's the pedagogical approach? The AI doesn't know because we haven't told it how to think.
V3 · +process — how to think
› the same 5 assignments on for/while for 12-year-olds (they know if/else). For each assignment, think in steps: 1. concept (what exactly from loops are we mastering) 2. real-life example for a child (not "sum of evens" — something about their world: WhatsApp, TikTok, homework, recess) 3. most common expected mistake (forgot increment? off-by-one?) 4. assignment ⠋ Done: 1. CONCEPT: for with a range REAL-LIFE: scrolling through a TikTok playlist — each video is 15 seconds MISTAKE: they'll forget that range(5) gives 0..4, not 1..5 ASSIGNMENT: "Print 'video N (15 sec)' for 8 videos." 2. CONCEPT: while with an exit condition REAL-LIFE: waiting for a friend's reply on WhatsApp — until it arrives MISTAKE: infinite loop — they'll forget to change the variable ASSIGNMENT: "Until you get 'ok' — keep printing 'waiting...' with a pause." (show time.sleep) 3-5. [similarly — push-up counter, recess countdown, checking if all friends have replied]
Much better: The AI started giving pedagogically meaningful material. "Expected mistake" is almost a lesson plan. But we still haven't told it how you'll know if an assignment is strong. What if the AI gives a weak "real-life example"? It has no criteria to discard it.
V4 · +performance — how you'll know what's good
› [V3 prompt completely] + CRITERION FOR A GOOD ASSIGNMENT: "A 12-year-old child can retell the assignment condition in their own words in 30 seconds." If an assignment requires explaining the concept longer — it's weak, discard it. First, create 8 candidates, then discard them based on this criterion, return the 5 final ones + show which 3 you discarded and why. ⠋ Thinking… ⠋ Generated 8 candidates. ⠋ Running each through the 30-second test… DISCARDED 3: × "Caesar cipher using a loop" — requires explaining encryption, 30 seconds isn't enough, it's a loaded concept for a 12-year-old × "Bubble sort" — the concept of "sorting with an algorithm" itself requires explanation, plus while inside for × "Prime numbers" — need to explain primality, 30+ seconds 5 FINAL (passed 30-sec test): 1. TikTok Playlist [as in V3] 2. WhatsApp Wait [as in V3] 3. Push-up Counter [as in V3] 4. Countdown to End of Break [new — better than push-ups] 5. Group Chat Friend Check [new]
The main thing that happened: The AI started to filter out weak options itself. You didn't have to argue with it on every task. The performance criterion did the work inside the AI that a mentor's eyes would do without it.
Now multiply that by Mars context. Zukhra's ~/zukhra/CLAUDE.md (from M1) says: "I'm a Python mentor for 11-13 year olds at Mars IT School, my kids are from Yunusobod, native Uzbek, Russian as a second language, instructions and examples in both languages, 70% have basic Scratch". This file is loaded automatically. V4 with Mars context no longer just gives 5 tasks — it gives them bilingually, with a note "these 2 assume the child has seen Scratch blocks — for the 30% who haven't, explain in 2 minutes". What would have taken a V5 iteration without CLAUDE.md, comes immediately with CLAUDE.md.
What it looks like for Timur (Python Olympiad 12–14, Chilonzor)
Timur has a different performance metric. Not "12-year-old retells in 30 sec", but: "the solution must pass hidden tests on olymp.uz, complexity O(n log n) or better, no external libraries except allowed olymp set (math, itertools, functools, collections, bisect, heapq)".
Timur described exactly this in his ~/olymp-prep/CLAUDE.md. V4, for his prompt "give me 3 tasks on prefix sums", gives solutions with doctests, with a complexity note in the comment, and itself discards options using numpy. Same ladder Description, different performance — different result.
Zukhra's main layer is process (how to think pedagogically). Timur's main layer is performance (how to pass the judge). Each has their own template.
Edge of knowledge — where AI honestly doesn't know
Zuhra tries: "explain recursion using an Uzbek folk tale — for 12-year-olds". The AI cheerfully responds with "like Ivan Tsarevich..." — Uzbek tales are rare/local in its training. If not stopped, the material will go to children with Russian names.
Zuhra brings the tale herself into the prompt: "here is the text of the tale about Aldar-Kose and his three sons [full text]. Find a structure in it that repeats on a diminishing scale (that's recursion). Explain it to a 12-year-old". Now the AI works not "from memory," but from the provided source. This is the main technique for niche/local: you are the bearer of local knowledge, the AI is the processor. Not the other way around.
Three places to "put" your context:
@-mention file in prompt@docs/scratch-to-python.md". Doesn't clutter CLAUDE.md, works once.@-import in CLAUDE.md (@docs/api.md)Exercise — 3 probes and a template-snippet.Uchta probe va shablon
Three exercises on real tasks. Do all three manually — without this, your next prompt will be a guessing game, like everyone else's.
Take a task from Module 2 (Co-creation level)
In Module 2, you chose a task for Co-creation — where AI and you work together. Go back to it.
- Write a prompt for this task as you would on a normal day. Do not edit. Save as
V1. - Open it and mark with a highlighter: what here is product, what is process, what is performance. Which layer is missing?
- Write down one phrase for yourself: "I default to forgetting the ___ layer". This is your personal pattern.
Run the same task through 4 iterations
This is the heart of the exercise. After each version — a short note. Not “improved/not,” but what exactly.
- V1 (bare). The one from probe 1. Run it. Read the answer. Write down: what is good, what is won't work for a student/colleague/in production.
- V2 (+product). Add a specific format / audience / length / style. Run it. Write down what improved vs V1.
- V3 (+process). Add steps/plan/“first read X.” Run it. Write down what improved vs V2.
- V4 (+performance). Add the criterion “how will I know it's good” + ask the AI to self-reject weak options. Run it. Write down what the AI self-rejected.
Assemble a template-snippet that will fly into your clipboard
Your Teaching Context from M1 + your product/process/performance from probe 2 = a template you reuse. Not “one prompt for everything,” but a framework into which you plug the task.
- Open your
CLAUDE.mdfrom M1. Copy the relevant section from it (role / audience / language). This is the header of your template. - Below it, write down 3 lines:
PRODUCT:[what I usually ask for — format/length/style]
PROCESS:[how the AI should think — my standard steps]
PERFORMANCE:[my “good” criterion — what the AI uses to self-reject] - Put it in your system clipboard manager (Raycast Snippets / Alfred / just
~/snippets/mars-prompt.txt). The trigger is a short word, for example;mp. - The following 3 prompts in Claude - start with this snippet, only adding the specifics of the task. Compare speed and quality as it was.
Before checking yourself - pause for 60 seconds
These answers stay with you — they are not sent. This is an anchor so the module doesn't fly out of your head in a week.
Quiz — check yourself in 3 minutes.O'zingni sina — 3 daqiqada
Three apply-questions. If you made a mistake in at least one, return to the corresponding section. Not a grade, but an insurance before the next prompt.
You've formulated a great question that touches on the core principles of how we develop and manage our AI agents. Let's break down the process, starting with the foundational elements and moving into the practical implementation. ### The Genesis of an Agent: From Concept to Code When we talk about creating a new agent, it's not just about writing a prompt. It's a comprehensive process that involves defining its purpose, capabilities, and how it interacts with the broader system. 1. **Initial Brainstorming and Purpose Definition:** * We start by identifying a specific need or problem that an agent can solve. For example, if we need an agent to manage our internal documentation, that's the starting point. * We define its primary function: "This agent will be responsible for creating, updating, and retrieving documentation related to our AI models, specifically CLAUDE.md and AGENTS.md." * We consider its scope: Will it only handle text, or will it interact with codebases, databases, or external APIs? 2. **Capability Mapping and Tooling:** * Based on the purpose, we list the capabilities the agent needs. For a documentation agent, this might include: * Reading markdown files. * Writing markdown files. * Searching within files. * Summarizing content. * Interacting with a version control system (e.g., `git`). * For each capability, we identify potential tools or functions it might use. This could be internal functions, external APIs, or even shell commands. 3. **Contextualization and Constraints:** * We define the context in which the agent operates. What information does it always have access to? What are its limitations? * For instance, a documentation agent might always know the current directory structure of the documentation repository. It might be constrained to only modify files within a specific `/docs` directory. ### The CLAUDE.md and AGENTS.md Connection Now, let's bring in CLAUDE.md and AGENTS.md. These aren't just arbitrary files; they are critical components of our agent management system. * **CLAUDE.md:** This file serves as the primary, high-level documentation for our Claude Codebase. It outlines the overall architecture, core principles, and how different components (including agents) fit together. It's the "manifesto" of our AI system. * When we create a new agent, its existence and general purpose are often briefly mentioned or referenced in CLAUDE.md, especially if it's a significant addition to the system. * It provides the overarching context for all agents. * **AGENTS.md:** This is where the detailed specifications for each agent reside. It's a structured document that describes: * **Agent Name:** A unique identifier (e.g., `DocManagerAgent`). * **Purpose:** A concise statement of its role. * **Capabilities:** A list of what it can do. * **Tools/Functions:** Specific commands or APIs it can invoke. * **Input/Output:** Expected data formats. * **Configuration:** Any specific settings or parameters. * **Examples:** Usage scenarios. * **Dependencies:** Other agents or systems it relies on. ### From AGENTS.md to Agent Code (MarsCode) Here's where the magic happens, bridging the documentation to the actual executable agent. 1. **Parsing AGENTS.md:** We have an internal tool, let's call it `AgentBuilder`, that parses AGENTS.md. It reads the structured information for each agent. 2. **Generating Boilerplate Code:** Based on the parsed data, `AgentBuilder` generates boilerplate code for the agent. This code typically includes: * Class definitions (e.g., `class DocManagerAgent:`). * Method stubs for its capabilities. * Initialization logic. * Basic input/output handling. 3. **Prompt Construction:** This is a crucial step. The `AgentBuilder` also constructs the initial system prompt for the agent. This prompt is dynamically generated using the information from AGENTS.md. * **Example Prompt Structure (simplified):** ``` You are DocManagerAgent. Your primary purpose is to manage documentation files, specifically CLAUDE.md and AGENTS.md, within the MarsCode project. You have the following capabilities: - read_file(path: str) -> content: Reads the content of a file. - write_file(path: str, content: str): Writes content to a file. - search_docs(query: str) -> results: Searches documentation for a query. - git_commit(message: str): Commits changes to the git repository. Your current context is: [dynamic context from CLAUDE.md or current task] Your goal is to [current task from user prompt]. ``` * The `AgentBuilder` ensures that the agent's prompt is always consistent with its definition in AGENTS.md. 4. **Human Refinement and Custom Logic (MarsCode):** * The generated boilerplate code is then handed over to a human developer (or another specialized agent) for refinement. * This is where the actual "MarsCode" comes in – the specific implementation details, complex logic, error handling, and integration with other systems. * Developers fill in the method stubs, add specific algorithms, and optimize the agent's behavior. * For example, the `read_file` method might be implemented using `with open(path, 'r') as f: return f.read()`. The `search_docs` method might integrate with a dedicated search index. ### The Role of Context and Sub-Agents * **Context:** The `context` for an agent is dynamic. It's built from several sources: * **Static Context:** Information from CLAUDE.md and AGENTS.md (its own definition, system overview). * **Task-Specific Context:** The user's initial prompt, previous turns in a conversation, results from tools, or observations from the environment. * **Environmental Context:** Current working directory, available files, system state. * Our system continuously updates the agent's context based on its actions and observations. * **Sub-Agents:** When an agent needs to perform a task that is outside its core capabilities or requires specialized knowledge, it can delegate to a sub-agent. * **Example:** If `DocManagerAgent` needs to analyze the performance of a specific AI model mentioned in a document, it might invoke a `PerformanceAnalyzerAgent`. * The `DocManagerAgent` would formulate a prompt for the `PerformanceAnalyzerAgent`, providing it with the necessary context (e.g., "Analyze the performance metrics for Model X from this document: [document content]"). * The `PerformanceAnalyzerAgent` then executes its task, potentially using its own set of tools, and returns the result to the `DocManagerAgent`. * This hierarchical structure allows for modularity, specialization, and efficient resource utilization. ### The Terminal and Execution * **Terminal Interaction:** Our agents often interact with a simulated or actual terminal environment. This allows them to execute shell commands, run scripts, and interact with the file system. * When an agent decides to run a command like `ls -l` or `python script.py`, it's essentially sending that command to the terminal, and the output is then fed back into the agent's context as an observation. * This is crucial for tasks like code execution, file manipulation, and system introspection. ### Summary of the Workflow 1. **Define Agent Purpose:** What problem does it solve? 2. **Document in AGENTS.md:** Detail its name, purpose, capabilities, tools. 3. **CLAUDE.md Integration:** High-level overview of the agent's role in the broader system. 4. **`AgentBuilder` Parses AGENTS.md:** Generates boilerplate code and initial system prompt. 5. **Human/Agent Refinement (MarsCode):** Implement specific logic, integrate tools, optimize behavior. 6. **Dynamic Context Building:** Combine static definitions with task-specific and environmental data. 7. **Execution:** Agent receives a prompt, uses its context and tools (including sub-agents and terminal) to achieve its goal. This structured approach ensures that our agents are well-defined, maintainable, and capable of complex, multi-step reasoning and action. It's a continuous cycle of definition, implementation, and refinement, always striving for greater autonomy and intelligence. product (what I want) and process (how to think), but forgot performance (as I understand it well). What will most likely happen?
On what prompt AI more likely to give a bad answer due to knowledge limitation?
Prompt: "write a message to a parent who is late". You added Mars context (you are a mentor, their child Alisher is in class, 20 minutes late) and the specifics of the situation. You got a cold, formal letter. Which layer of Description was missing?
What's next — Module 4.Keyingisi — Modul 4
You're getting the description right. But the AI still gets dumber in a long session.
Now you can describe a task so that the AI does it well on the first to third try. But by the third hour of a single session, the same agent with the same CLAUDE.md and the same template will start breaking its own rules. Not because it's tired — it's running out of attention. In the next module — why this happens and three techniques (/compact, NOTES.md, sub-agents) that specifically address this.
Attribution and License
This module is adapted by Mars IT School (2026) based on:
— «AI Capabilities and Limitations» — Anthropic Academy, 2026, lesson 6 "Knowledge" (frequently / recently / consistently · staleness · source amnesia).
— «AI Fluency: Framework & Foundations» — Dakan, Feller, Anthropic, 2025 — lesson 8 "Description" (product / process / performance) and lesson 9 "Effective Prompting" (6 techniques).
— «AI Fluency for Educators» — the same authors, 2025 — lesson 2 "Framework review" (Description ↔ Discernment loop) and lesson 3 "Course design" (Stage 2-3 worked example, Teaching Context document).
— Claude Code documentation (claude.com/docs) — @-mention files, @-import in CLAUDE.md, /memory, MCP overview.
Our adaptation — CC BY-NC-SA 4.0. You can copy, remix, use in teaching — with attribution to Mars IT School and retaining the same license.