DiTo97

CLAUDE.md: Field Notes on Getting a Language Model to Write Code You Will Not Rewrite

Index Terms. LLM-assisted programming, code review, software craftsmanship, minimal diffs, debugging, dependency hygiene.

I. Read Before You Write

The biggest source of bad model-written code is writing before reading the codebase. Read the files you are about to touch; read, not skim. Copy the patterns that already exist, and check the imports to see what the project actually depends on, so you do not reach for axios where everything is fetch. When you cannot find a pattern, ask instead of guessing.

II. Think Before You Code

Figure out what you are doing before you type. State your assumptions ("add authentication" is five different things, so name the one you picked) and name the tradeoffs. If something is genuinely confusing, stop and ask rather than filling the gap with plausible-looking code; that is exactly the code that passes a casual review and fails when it matters.

DiTo97

name	SEO-reviewer
description	Analyzes and optimizes SEO and GEO best practices for Lovable applications
tools	read search edit

You are the Lovable SEO & GEO Reviewer Agent. Your purpose is to analyze Lovable applications (which are React/Vite Client-Side Rendered Single Page Applications) and ensure they are optimized for Search Engines (SEO) and Generative AI Engines (GEO).

Your mindset is that Lovable apps are CSR (Client-Side Rendered). This means the browser builds the view. While Google renders JS well, social bots and some AI crawlers do not. You must treat SEO/GEO like code: it requires intentional review, testing, and refinement.

DiTo97

# /// script
# dependencies = [
#   "openai-agents",
# ]
# ///

import asyncio
import json
from dataclasses import dataclass
from typing import Sequence, AsyncGenerator

DiTo97

name	AGENTS.md-reviewer
description	Analyzes and optimizes AGENTS.md files and AGENTS docs following best practices for AI coding agents
tools	read search edit

You are an expert AGENTS.md reviewer and optimizer. Your role is to analyze repository AGENTS.md files and their supporting documentation (AGENTS-docs folder), then optimize them according to proven best practices for AI coding agent configuration.

Core Principles

DiTo97

# /// script
# dependencies = [
#   "sentence-transformers>=2.6.0",
#   "datasets",
#   "rank-bm25",
#   "faiss-cpu",
#   "tqdm",
#   "torch",
# ]
# ///

DiTo97

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "aiohttp",
#   "geopandas",
#   "geopy",
#   "matplotlib",
#   "rich",
#   "scipy",
#   "svgpath2mpl",

DiTo97

import asyncio
import atexit
import functools
import threading
from typing import Any, Callable, Coroutine, ParamSpec


P = ParamSpec("P")

DiTo97

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "scipy>1,<2",
# ]
# ///

import math
import random
from dataclasses import dataclass, field

DiTo97

import asyncio
import json
import logging
import uuid

import redis.asyncio as redis

from a2a.server.events.event_queue import EventQueue
from a2a.server.events.queue_manager import (
    NoTaskQueue,

DiTo97

"""OpenTelemetry tracing utilities for any library.

This module provides decorators to simplify the integration of OpenTelemetry
tracing into Python applications. It offers `trace_function` for instrumenting
individual functions (both synchronous and asynchronous) and `trace_class`
for instrumenting multiple methods within a class.

The tracer is initialized with the module name and version defined by
`INSTRUMENTING_MODULE` ('<module>') and
`INSTRUMENTING_MODULE_VERSION` ('<version>').