writing-derived-artifact-claude-md

name	writing-derived-artifact-claude-md
description	Use when initializing CLAUDE.md for a derived or projected directory — symlink view, build cache, mirror, generated docs, materialized projection — where the directory's content is regenerated from an upstream source by a tool or script.

Writing CLAUDE.md for a derived artifact

Overview

A derived artifact is a directory whose content is regenerated from an upstream source: symlink views, build caches, mirror repos, generated docs, materialized projections, manifest-driven layouts. Editing in place is either pointless (overwritten on next regen) or dangerous (mutates upstream through a symlink, bypassing upstream's review gates).

A capable agent writing CLAUDE.md for a derived artifact will usually catch the obvious traps (don't edit symlinks, don't hand-edit generated metadata). They will usually miss three subtler things — this skill exists to add those three.

When to Use

Use when the target directory shows any of these signals:

• Most files under content dirs are symlinks pointing elsewhere
• A .meta/ or similar dir contains JSONL build logs, checksums, or projection scores
• A sibling directory has the same shape but different content (e.g., *-readonly, *-admin, *-full)
• The README or any in-tree note refers to a "generator", "manifest", "rebuild", "projection", "view"
• The directory has no manifest files (package.json, Cargo.toml, etc.) — it's not code, it's content

Do not use when:

• The directory is a code repo (use /init directly)
• The directory is the upstream source itself (it owns its governance — write that CLAUDE.md normally)
• The directory has only one file and no metadata — too thin to warrant ceremony

The three audit moves (RED→GREEN delta)

A baseline agent will discover the generator, document the symlink trap, and list a rebuild command. That's table stakes. Before writing the file, also do:

1. Family scan

ls the parent directory. Document every sibling artifact with the same shape, not just the one you happened to land on. If the target is ~/Desktop/dash-kv-view-readonly, the family is view-readonly, view-admin, view-full — each likely a different profile of the same generator. The CLAUDE.md must name the whole family, not pick one and call it "the sister."

2. Upstream governance trace

The natural advice "to change content, edit upstream and regenerate" is incomplete when upstream has its own review/ingest/audit rules. Before claiming the edit-upstream path is open:

• Read upstream's CLAUDE.md (if any)
• Read upstream's README / CONTRIBUTING / ingest rules / SOP / governance docs
• Surface in the derived-artifact CLAUDE.md any upstream constraint that governs the edit-upstream step (review gates, secret-scrubbing, audit logging, approval flows)

If you don't, the new session reads "edit upstream then regenerate", does exactly that, and bypasses upstream's review chain. This is how incidents happen.

3. Production vs template/example

Is this a production instance (real data, real consequences) or a template/example/sandbox (safe to break)? Production instances need stronger language ("violating this triggers an incident", reference to actual incident postmortems if any). Templates need less.

Source signals: real PII / financial / customer data → production. Synthetic / placeholder / EXAMPLE_* data → template.

CLAUDE.md template structure

Use this section order. Replace the bracketed text.

# CLAUDE.md

[1-line: this directory is a derived artifact of <upstream>, generated by <tool>.]

## Source of truth
- Upstream: <absolute path>
- Generator: <script path + version>
- Manifest: <path + schema in one line if non-obvious>
- Profile: <which projection of upstream this is>

## Sibling artifacts
[List every sibling, what each contains, when to use which.]

## Don't do these
1. Don't edit files under <content-dirs>/ — they're symlinks; edits mutate upstream.
2. Don't hand-edit <meta-dirs>/ — regenerated on every rebuild.
3. Don't `rm` or `mv` symlinks — change the manifest, then rebuild.
4. [Profile-specific: "don't promote restricted-tier content into this profile"]

## Upstream governance
[The audit-move-2 output. If upstream has review/ingest rules that govern the "edit upstream → regenerate" path, name them and link to upstream's authoritative docs. Example: "See <upstream>/CLAUDE.md and <upstream>/INGEST-RULES.md. Editing upstream content still requires the [memory proposal] → reviewer scoring → final approval flow — direct writes to upstream bypass the audit chain."]

## Rebuilding
[Exact command with all args. Note idempotency, what gets preserved (this CLAUDE.md), what gets clobbered.]

## Consumer contract (if any)
[What downstream tools consume this artifact and what shape they expect.]

Anti-patterns

❌	✅
"Quick Commands" section with npm test / make lint	Drop the section — derived artifacts don't have build/test/lint targets
"Sister view: dash-kv-view-admin (the full one)"	"Sister views: view-readonly, view-admin, view-full — each a different profile"
"To change content, edit upstream and rebuild"	Same line + "Upstream is governed by [link to upstream CLAUDE.md / INGEST-RULES]; direct writes bypass audit."
Treating the artifact as a workspace ("you can edit files here")	Explicit: "this is a read-only projection, not a scratchpad"
Listing every file currently linked in	Describe the kind of content; the specific file list rots on every rebuild

Common mistakes

• Forgetting the family scan — leads to incomplete sibling section, future sessions don't realize they can switch profile.
• Stopping at "edit upstream" — the most common gap; what makes incidents.
• Including the current symlink list — manifest-driven content changes; the list goes stale immediately.
• Writing it as if it's the upstream's CLAUDE.md — derived artifact's CLAUDE.md should be ~50% upstream pointer + governance, ~50% "don't break the projection", not a copy of upstream's policy.

Red flags — stop and re-audit

• You wrote "edit upstream and regenerate" without reading upstream's governance docs.
• You named only one sibling artifact.
• You included exact filenames currently in the directory in the CLAUDE.md.
• You added a "## Build" or "## Testing" section.

If any of these happened, the skill wasn't applied. Re-audit before committing.