{"id":32848529,"url":"https://github.com/aviadr1/claude-meta","last_synced_at":"2026-05-12T23:34:33.792Z","repository":{"id":323083347,"uuid":"1092065411","full_name":"aviadr1/claude-meta","owner":"aviadr1","description":"Self-improving AI: Transform CLAUDE.md into a learning system. One prompt makes Claude learn from every mistake. Meta-rules + reflection = continuous improvement.","archived":false,"fork":false,"pushed_at":"2025-11-08T00:21:17.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-08T02:30:50.346Z","etag":null,"topics":["ai","ai-automation","ai-prompts","best-practices","claude","claude-code","developer-tools","documentation","machine-learning","self-improving"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aviadr1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T00:00:09.000Z","updated_at":"2025-11-08T00:29:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aviadr1/claude-meta","commit_stats":null,"previous_names":["aviadr1/claude-meta"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aviadr1/claude-meta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviadr1%2Fclaude-meta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviadr1%2Fclaude-meta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviadr1%2Fclaude-meta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviadr1%2Fclaude-meta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aviadr1","download_url":"https://codeload.github.com/aviadr1/claude-meta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviadr1%2Fclaude-meta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283333707,"owners_count":26818628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-08T02:00:06.281Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-automation","ai-prompts","best-practices","claude","claude-code","developer-tools","documentation","machine-learning","self-improving"],"created_at":"2025-11-08T10:00:32.065Z","updated_at":"2025-11-08T10:01:42.902Z","avatar_url":"https://github.com/aviadr1.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Self-Improving AI: One Prompt That Makes Claude Learn From Every Mistake\n\n![Reflect → abstract → generalize → CLAUDE.md loop illustration](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j9tukkbs0brnnjrdf3a2.jpg)\n\nThis repository captures a complete playbook for transforming `CLAUDE.md` from static documentation into a self-improving system. Below you'll find the full article that explains the workflow, along with quick links to the reusable templates that live in this repo.\n\n\u003e ⭐️ **Enjoy this playbook?** Please star the repo, share your results, and open issues or discussions with ideas we should fold back into the templates.\n\n## Quick Links\n- [Starter `CLAUDE.md` template](CLAUDE_TEMPLATE.md)\n- [Full production example](CLAUDE_FULL.md)\n- [Jump to the meta-rules](#the-meta-rules-teaching-ai-how-to-learn)\n- [Jump to the magic prompt](#the-magic-prompt-one-sentence-changes-everything)\n\n---\n\nI'm going to share a magical prompt and a beautiful structure for `CLAUDE.md` that makes Claude Code better every time it makes\na mistake.\n\n## The Untapped Potential\n\nMost repositories have a `CLAUDE.md` file—it's standard practice. But here's what we're missing: we have thousands of tokens of\ncognition at the start of every session. Why treat CLAUDE.md like static documentation when we could turn it into a **self-impro\nving system**?\n\nThe breakthrough is making it trivially easy for the AI to improve itself continuously, using that abundant reasoning capacity t\no compound learning over time.\n\n## Where Human and AI Cognition Should Focus\n\nHere's the key insight about working with AI. Human cognition is best used for critical thinking, spotting mistakes, preventing\nrepeating patterns, laying down clearly what we're trying to achieve and why, and setting guardrails to ensure work is done corr\nectly.\n\nAI cognition, relative to human time and cognitive load, is best used for executing on well-defined instructions, analyzing patt\nerns from recent context, writing structured documentation, and maintaining consistency across large codebases.\n\nAs fast-paced engineers, our cognitive load is high and our time is limited. Having the very enthusiastic Claude execute on our\nguardrails and self-improve through the system we offer makes the work become self-improving with compounding benefits.\n\n## The Innovation: Two Simple Ideas\n\nWhat makes this work is the combination of two deceptively simple ideas.\n\n**First**, a structure that teaches the AI how to teach itself. Most CLAUDE.md files just list rules. Mine includes meta-rules a\nbout how to write rules. This means when Claude adds new content, it automatically maintains quality and consistency. The docume\nnt doesn't just grow—it grows well.\n\n**Second**, a single prompt that transforms every mistake into permanent learning. When Claude makes a mistake, instead of just\nfixing it and moving on, I use one sentence that triggers an entire self-improvement cycle. Claude reflects on what went wrong,\nabstracts the general pattern, and writes it down following the meta-rules it just read.\n\nLet me show you how each piece works.\n\n## The Meta-Rules: Teaching AI How to Learn\n\nThe real innovation is in the META section of CLAUDE.md. This section exists for one purpose: to teach Claude how to write good\nrules when it makes mistakes.\n\nHere's what mine looks like:\n\n```markdown\n## META - MAINTAINING THIS DOCUMENT\n\n### Writing Effective Guidelines\n\nWhen adding new rules to this document, follow these principles:\n\n**Core Principles (Always Apply):**\n1. Use absolute directives - Start with \"NEVER\" or \"ALWAYS\"\n2. Lead with why - Explain the problem before the solution (1-3 bullets max)\n3. Be concrete - Include actual commands/code\n4. Minimize examples - One clear point per code block\n5. Bullets over paragraphs - Keep explanations concise\n\n**Optional Enhancements (Use Strategically):**\n- ❌/✅ examples: Only when the antipattern is subtle\n- \"Warning Signs\" section: Only for gradual mistakes\n- \"General Principle\": Only when abstraction is non-obvious\n\n**Anti-Bloat Rules:**\n- ❌ Don't add \"Warning Signs\" to obvious rules\n- ❌ Don't show bad examples for trivial mistakes\n- ❌ Don't write paragraphs explaining what bullets can convey\n```\n\nThink about what this does. Every time Claude reads CLAUDE.md at the start of a session, it learns not just your project's rules\n but how to write new rules. When it makes a mistake later in that session and you trigger the reflection prompt, Claude already\n knows the format to use, when to add detail versus keep it brief, and how to avoid bloat.\n\nThis is the key that unlocks continuous self-improvement. Without meta-rules, Claude would add verbose, inconsistent content tha\nt degrades the document over time. With meta-rules, Claude self-regulates. It asks itself \"Should I add a 'Warning Signs' sectio\nn here?\" and checks the meta-rules to decide. The quality of what it writes compounds rather than degrades.\n\nThe meta-rules also include a simple instruction that whenever Claude adds a new rule to the detailed sections, it must update t\nhe summary section at the top. This creates a two-tier structure where Claude can quickly scan absolute rules at session start,\nthen reference detailed sections while writing code. Adding a new rule becomes frictionless—one line in the summary, one detaile\nd section following the meta-rules.\n\n## The Magic Prompt: One Sentence Changes Everything\n\nWhen Claude makes a mistake, after correcting it, I use this prompt:\n\n\u003e **\"Reflect on this mistake. Abstract and generalize the learning. Write it to CLAUDE.md.\"**\n\nThat's it. One sentence. But look at what happens when Claude processes this instruction.\n\n**Reflect** tells Claude to analyze what went wrong and why, not just acknowledge the correction. Claude has perfect context—the\n mistake is right there in working memory with all the surrounding code. This reflection captures nuances that would be lost if\nyou tried to document it manually later.\n\n**Abstract** tells Claude to extract the general pattern from the specific instance. If Claude patched a logger, the abstraction\n isn't \"don't patch logger\" but \"don't patch widely-used infrastructure.\" This is where the AI's pattern recognition shines—it c\nan see the underlying principle.\n\n**Generalize** tells Claude to create a reusable decision framework. Not just a rule, but guidance on how to think about similar\n situations in the future. \"When you see X, ask yourself Y.\"\n\n**Write it to CLAUDE.md** triggers Claude to follow all the meta-rules it read at session start. Use NEVER or ALWAYS. Lead with\nwhy. Keep it concise. Update the summary. All of this happens automatically because the meta-rules have already set the guardrai\nls.\n\nYou've automated an entire learning cycle with one sentence. Claude does the execution work—analyzing, abstracting, documenting,\n maintaining format. You did the critical thinking—spotting that a pattern exists worth capturing.\n\n## Why This Creates Compounding Improvement\n\nThe magic is in the compounding loop this creates. Session one, Claude makes three mistakes. You use the prompt three times. Thr\nee new rules get added to CLAUDE.md. Five seconds of your time per rule.\n\nSession two, Claude reads those rules at startup. It doesn't make those three mistakes anymore. Instead it makes new, more sophi\nsticated mistakes. You capture those. Five seconds per rule again.\n\nSession three, Claude reads all the accumulated rules. The basic mistakes have vanished. Now you're having discussions about arc\nhitectural trade-offs instead of fighting about whether imports go at the top of files.\n\nThe mistakes evolve upward. This is exactly what you want from a learning system. You're not eliminating mistakes—you're elevati\nng the conversation to increasingly sophisticated levels.\n\nAnd here's what makes it sustainable: the meta-rules ensure that as the document grows, quality doesn't degrade. Claude self-reg\nulates based on the guidelines you set once. The document maintains consistency automatically. You're not manually editing every\n addition—Claude enforces its own standards.\n\n## The Deep Insight: Automation Within Automation\n\nWhat makes this work at a fundamental level is understanding the economics of human versus AI cognition. Your time and cognitive\n load are the scarce resources. AI execution capacity is abundant relative to that.\n\nTraditional documentation is expensive because it consumes scarce human time. Writing it is expensive. Maintaining it is expensi\nve. Keeping it consistent is expensive. So documentation often doesn't happen or becomes stale.\n\nBut with AI, execution is abundant. Claude is going to read CLAUDE.md at every session start anyway—that cognition is already be\ning spent. Claude can analyze patterns in milliseconds. Claude can write structured text faster than you can read it. So why not\n put that abundant capacity to work?\n\nThe reflection prompt does exactly this. You spend five seconds providing the critical thinking—spotting that a pattern exists w\north capturing. Claude spends its abundant execution capacity doing the analysis, abstraction, and documentation. The marginal c\nost of improvement drops to nearly zero, so improvement happens constantly.\n\nYou're creating automation within automation. The AI uses its own reasoning to make itself better at reasoning about your code.\nAnd because you've set clear guardrails with meta-rules, the quality compounds rather than degrades.\n\n## Getting Started: Two Templates\n\nI'm providing two files to help you implement this system.\n\n**CLAUDE_TEMPLATE.md** is a minimal starting point with the two-tier structure, the essential meta-rules, and a few universally\nuseful rules like keeping imports at the top of files and avoiding magic numbers in tests. Use this if you're starting fresh or\nwant a clean foundation to customize.\n\n**CLAUDE_FULL.md** is our complete CLAUDE.md showing what the system looks like after months of evolution. It includes project-s\npecific guidelines, examples of well-written rules at various sophistication levels, and demonstrates how the meta-rules maintai\nn quality as the document grows. Use this if you want to see a fully-evolved example or work in a similar tech stack.\n\nBoth files demonstrate the structure and show you what a self-improving CLAUDE.md looks like in practice.\n\n## What This Really Is\n\nThis pattern reveals something profound about working with AI. Current AI has three fundamental limitations when coding: no proj\nect memory across sessions, no learning mechanism from corrections, and expensive fine-tuning requirements.\n\nThis approach solves all three using only a markdown file, a structured format, and one magic prompt. CLAUDE.md provides memory—\nit's read every session. The reflection prompt provides learning—mistakes become permanent lessons. The meta-rules provide quali\nty control—the AI maintains its own standards.\n\nYou're creating a crude but effective form of continuous learning. No special tools. No API access. No fine-tuning costs. Just s\nmart allocation of human critical thinking and AI execution capacity.\n\nThe deeper pattern is about self-reinforcing loops. The best workflows with AI aren't linear sequences—they're loops where the o\nutput feeds back to improve the input. Every mistake makes the system smarter. Every correction improves future sessions. Every\nrule makes the next rule easier to learn.\n\n## Conclusion: The Division of Labor\n\nThe breakthrough isn't having a CLAUDE.md file—everyone has that. The breakthrough is making it trivially easy for the AI to imp\nrove itself continuously while you focus on critical thinking.\n\nYou provide the critical thinking: spotting patterns, preventing problems, setting guardrails, deciding what matters. Claude pro\nvides the execution: analyzing mistakes, extracting principles, writing documentation, maintaining consistency.\n\nThe meta-rules ensure quality compounds as the document grows. The reflection prompt automates the entire improvement cycle. Tog\nether they create a system where every mistake becomes permanent learning with minimal human effort.\n\nYou're not just documenting standards. You're building a system that teaches itself while you focus on what humans do best: the\ncritical thinking that spots patterns and sets direction.\n\nThe magic words are simple: **\"Reflect, abstract, generalize, add to CLAUDE.md\"**\n\nThat's the prompt that turns abundant AI execution into continuous self-improvement, with your critical thinking as the guide.\n\n---\n\nWe love hearing how you're adapting this workflow. Star the repo if it helps you, open issues with questions or improvements, an\nd share success stories so the loop keeps compounding.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviadr1%2Fclaude-meta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faviadr1%2Fclaude-meta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviadr1%2Fclaude-meta/lists"}