GoingNinja Manual Knowledge Wiki logo
GoingNinja Manual Knowledge Wiki Lean MVP bootstrap documentation // Felix Rascher (WIP)

Instruction Files

This page explains how the repo describes itself to the current builder CLI, Claude Code, and Gemini CLI without maintaining three drifting copies of the same policy.

The rule is simple: write shared repo truth once, keep vendor adapters thin, and keep machine behavior in settings files.

1. The File Pattern

File Role Class
AGENTS.md canonical shared repo contract GoingNinja convention
CLAUDE.md thin Anthropic adapter official file surface used in a GoingNinja way
GEMINI.md thin Gemini adapter official file surface used in a GoingNinja way
.claude/settings.json Claude permissions and tool policy official
.gemini/settings.json Gemini context and behavior settings official surface, platform-enforced configuration

Default rule:

  • put shared repo truth into AGENTS.md
  • keep CLAUDE.md and GEMINI.md short
  • use settings files for permissions and tool behavior, not for prose explanation
  • let the current builder CLI attach and use that shared repo truth when scoping work or writing audits
  • let Claude and Gemini consume that shared truth through their own adapter path when reviewing

2. What Goes Into Each File

File What goes inside What stays out
AGENTS.md repo purpose, read order, hard rules, write boundaries secrets, temporary notes, long product specs
CLAUDE.md @ imports of shared repo truth, only Claude-specific reminders copied policy manuals
.claude/settings.json permissions, env policy, tool policy architecture prose
GEMINI.md Gemini-specific reminders; shared repo truth is loaded through .gemini/settings.json copied policy manuals
.gemini/settings.json explicit context loading and Gemini behavior architecture prose

Minimal Claude adapter:

# Claude Code Instructions

@AGENTS.md
@docs/architecture.md
@docs/vendor-sources.md

Platform-configured Gemini context:

{
  "context": {
    "fileName": [
      "AGENTS.md",
      "GEMINI.md"
    ]
  }
}

See Vendor Sources for the split between vendor-native behavior and GoingNinja convention. This page only describes the file pattern inside a generated repo.

3. The Startup Chain

Startup should begin from repo files, not from chat memory.

Tool Reads first Settings surface Status
current proof builder role operator-attached AGENTS.md — live today, manual attachment
Claude Code CLAUDE.md .claude/settings.json live today, repo-native startup
Gemini CLI configured context: AGENTS.md + GEMINI.md via .gemini/settings.json .gemini/settings.json live today, repo-configured startup

Claude and Gemini already have repo-grounded startup surfaces. The current proof builder surface still depends on the operator attaching AGENTS.md at session start because no equivalent repo-local settings file is documented today.

Adapter asymmetry also matters:

  • AGENTS.md defines the full human read order and the canonical repo contract
  • CLAUDE.md imports only the highest-value files for Claude's review startup path
  • GEMINI.md stays thin because Gemini receives shared repo context through .gemini/settings.json

That asymmetry is intentional. It keeps review startup light without changing the canonical contract.

Startup syntax note:

  • @file is a Claude-native import mechanism
  • Gemini receives repo context through .gemini/settings.json, so GEMINI.md names the shared files but does not import them with @file

4. Conflict Resolution

The system needs an explicit rule for conflicts between vendor adapters.

Precedence for conflicting rules:

  1. INVARIANTS.md wins on hard repo rules
  2. PLAN.md wins on current intended scope
  3. AGENTS.md wins on shared repo behavior
  4. CLAUDE.md, GEMINI.md, and vendor settings may narrow behavior for one tool, but may not override 1–3

This order exists for one reason: hard repo rules should beat current scope, and current scope should beat tool-specific behavior.

Current enforcement boundary:

  • this precedence is a documented contract today
  • deterministic CI does not yet parse these files semantically
  • conflicts are currently surfaced by review and audit, not by a dedicated precedence checker

Boundary of vendor files:

  • vendor adapter files may only narrow behavior for that one tool
  • vendor settings files decide permissions and context loading, not product policy

This keeps conflicts small and visible.

5. Sources