agentleFS
joelbarmettlerUZHjoelbarmettlerUZH/ultrainit.sh/schemas/CLAUDE.md

ultrainit.sh / schemas

CLAUDE.md8 starsChanged 7 months agoApache-2.0View on GitHub

14 JSON Schema files defining the structured output contract for every claude -p agent and synthesis pass. All schemas are validated in CI via jq empty. Every schema and every nested object uses additionalProperties: false. This is the single most important convention — it prevents Claude from hallucinating fields beyond the declared contract. Never add an object to a schema without this key. All categorical distinctions must be enums, never free-form strings: - structure-scout.json: 23-value role enum, 3-value priority enum…

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every schema and every nested object uses additionalProperties: false.

    line 28
  2. Distinctive:

    All categorical distinctions must be enums, never free-form strings:

    line 32

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

schemas/ — Agent Output Contracts

14 JSON Schema files defining the structured output contract for every claude -p agent and synthesis pass. All schemas are validated in CI via jq empty.

File Index

SchemaAgentPhaseKey Fields
identity.jsonidentity1name, description, languages, frameworks, monorepo, packages
commands.jsoncommands1build, test, lint, format, typecheck, other (via $defs)
git-forensics.jsongit-forensics1hotspots, temporal_coupling, bug_fix_density, ownership_diffusion
patterns.jsonpatterns1patterns[].{name, type, evidence_files, description, is_consistent}
tooling.jsontooling1tools[].{name, config_path, enforced_in_ci, has_pre_commit}
docs.jsondocs-scanner1documents, documented_conventions, undocumented_gaps
security.jsonsecurity-scan1protected_files[].{path_pattern, reason, safe_alternative}
structure-scout.jsonstructure-scout1directories[].{path, role, priority, should_have_claude_md}
module-analysis.jsonmodule-analyzer1 Stage 2module_path, purpose, key_files, patterns, gotchas
domain-research.jsondomain-researcher3domain_knowledge, framework_practices, common_pitfalls
mcp-recommendations.jsonmcp-discoverer3servers[].{name, command, args, env, relevance}
synthesis-docs.jsonsynthesizer-docs4 Pass 1claude_md (string), subdirectory_claude_mds[]
synthesis-tooling.jsonsynthesizer-tooling4 Pass 2skills[], hooks[], subagents[], mcp_servers[], settings_hooks[]
synthesis-output.jsonmerged output4merged shape of docs + tooling passes

Universal Rules

additionalProperties: false Everywhere

Every schema and every nested object uses additionalProperties: false. This is the single most important convention — it prevents Claude from hallucinating fields beyond the declared contract. Never add an object to a schema without this key.

Enum-Driven Categorical Fields

All categorical distinctions must be enums, never free-form strings:

  • structure-scout.json: 23-value role enum, 3-value priority enum (high, medium, low)
  • patterns.json: 9-value type enum
  • synthesis-tooling.json: hook events constrained to [PreToolUse, PostToolUse, Notification, Stop]

This enables safe downstream filtering with select(.priority == "high") without defensive string matching.

Optional Arrays (Never Nullable)

Fields that only apply conditionally are excluded from required but declared as array type — never as nullable scalars. Consumers can always use jq .field[]? safely. Example: identity.json.packages (only for monorepos), module-analysis.json.commands.

Markdown/Bash as Opaque Strings

synthesis-docs.json and synthesis-tooling.json store full document content (CLAUDE.md text, SKILL.md with YAML frontmatter, bash hook scripts) as plain JSON strings. Schema validation ends at the string boundary. YAML validity, shebang presence, set -euo pipefail — all checked externally by scripts/validate-skill.sh and validate.sh.

Known Schema Issues

synthesis-output.json is not passed to claude -p. It describes the shape of the jq -s '.[0] * .[1]' merged file. If either synthesis pass produces an unexpected top-level key, the merge silently overwrites with the second file's value. Validate the merged output manually if debugging merge issues.

Enum constraints are guidance, not hard enforcement. claude -p may return values outside declared enums (e.g., priority: "critical" instead of "high"). Downstream jq select() filters silently skip unexpected values. Add explicit validation in lib/gather.sh after structure-scout output is written if you need strict enforcement.

identity.json.packages has a conditional dependency. It should only be populated when monorepo: true, but the schema cannot express this. Downstream consumers must check monorepo === true before iterating packages.

Two MCP schema shapes exist. mcp-recommendations.json includes relevance and a nested configuration object. synthesis-tooling.json flattens command/args/env to top level. The synthesizer prompt must reshape MCP data. When debugging MCP config issues, check both schemas side-by-side.

developer-answers.json has no schema. It is hand-assembled by lib/ask.sh. Field names (project_purpose, deployment_target, never_do, common_mistakes, additional_context) are a de-facto schema. Any change to ask.sh output keys requires updating all jq expressions in synthesize.sh.

settings_hooks[] entries must have matching hooks[] entries. The schema does not enforce this relationship. validate.sh checks it after synthesis. If adding a hook to a synthesizer prompt, always generate both the hooks[] content entry and the settings_hooks[] wiring entry in the same response.

Module findings file collision. module-analysis.json is reused for all deep-dive agents but output files are named module-<dirname>.json. Two directories with the same basename (e.g., src/api and lib/api) will collide. lib/gather.sh should use full-path slugs rather than basename only.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.