From 15357c0af2608a981e53e5ebc7536cdce926e865 Mon Sep 17 00:00:00 2001 From: skal Date: Thu, 5 Mar 2026 23:06:45 +0100 Subject: docs: streamline and align AI context files Synchronized GEMINI.md and CLAUDE.md to provide a consistent and comprehensive context-loading structure for both AI agents. - Consolidated the Tier 3 (Design Docs) and Tier 4 (Archive) sections to include a detailed, verified list of all relevant documentation. - Standardized the use of the '@' prefix for all file paths, assuming a common loader directive. - Ensured project rules and maintenance guidelines are identical between both files. --- CLAUDE.md | 47 +++++++++++++++++++++++++++++++---------------- GEMINI.md | 62 +++++++++++++++++++------------------------------------------- 2 files changed, 50 insertions(+), 59 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5e987bd..e525708 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,35 +1,50 @@ -# TIER 1: CRITICAL (Always Loaded) +# ============================================ +# TIER 1: CRITICAL CONTEXT (Always Loaded) +# ============================================ @PROJECT_CONTEXT.md @TODO.md @README.md -# TIER 2: REFERENCE (Always Loaded) +# ============================================ +# TIER 2: TECHNICAL REFERENCE (Always Loaded) +# ============================================ @doc/HOWTO.md @doc/CONTRIBUTING.md @doc/AI_RULES.md @doc/EFFECT_WORKFLOW.md +# ============================================ # TIER 3: DESIGN DOCS (Load On-Demand by Subsystem) +# ============================================ # -# Audio: SPECTRAL_BRUSH_EDITOR.md, TRACKER.md, BEAT_TIMING.md -# CNN: cnn_v1/docs/CNN_V1_EFFECT.md, cnn_v2/docs/CNN_V2*.md -# 3D/Graphics: 3D.md, GPU_PROCEDURAL_PHASE4.md, MASKING_SYSTEM.md, SDF_EFFECT_GUIDE.md -# Scene: SCENE_FORMAT.md, SEQUENCE.md, WORKSPACE_SYSTEM.md -# Build: ASSET_SYSTEM.md, BUILD.md, CMAKE_MODULES.md, SIZE_MEASUREMENT.md -# Rendering: GEOM_BUFFER.md, SHADER_REUSE_INVESTIGATION.md, UNIFORM_BUFFER_GUIDELINES.md, WGPU_HELPERS.md, AUXILIARY_TEXTURE_INIT.md -# Tools: test_demo_README.md, HOT_RELOAD.md, HEADLESS_MODE.md, RECIPE.md -# Arch: ARCHITECTURE.md, CODING_STYLE.md, BACKLOG.md, TOOLS_REFERENCE.md, CONTEXT_MAINTENANCE.md +# Audio: @doc/SPECTRAL_BRUSH_EDITOR.md, @doc/TRACKER.md, @doc/BEAT_TIMING.md +# CNN: @cnn_v1/docs/CNN_V1_EFFECT.md, @cnn_v2/docs/CNN_V2.md, @cnn_v2/docs/CNN_V2_BINARY_FORMAT.md +# 3D/Graphics: @doc/3D.md, @doc/GPU_PROCEDURAL_PHASE4.md, @doc/MASKING_SYSTEM.md, @doc/SDF_EFFECT_GUIDE.md +# Scene: @doc/SCENE_FORMAT.md, @doc/SEQUENCE.md, @doc/WORKSPACE_SYSTEM.md +# Build: @doc/ASSET_SYSTEM.md, @doc/BUILD.md, @doc/CMAKE_MODULES.md, @doc/SIZE_MEASUREMENT.md +# Rendering: @doc/GEOM_BUFFER.md, @doc/SHADER_REUSE_INVESTIGATION.md, @doc/UNIFORM_BUFFER_GUIDELINES.md, @doc/WGPU_HELPERS.md, @doc/AUXILIARY_TEXTURE_INIT.md +# Tools: @doc/test_demo_README.md, @doc/HOT_RELOAD.md, @doc/HEADLESS_MODE.md, @doc/RECIPE.md, @doc/TOOLS_REFERENCE.md +# Arch: @doc/ARCHITECTURE.md, @doc/CODING_STYLE.md, @doc/BACKLOG.md, @doc/CONTEXT_MAINTENANCE.md -# TIER 4: ARCHIVE (Historical/Debugging Only) -# Active: COMPLETED.md, CNN_DEBUG.md -# Archived: doc/archive/* (handoffs, analyses, build proposals, cleanups) +# ============================================ +# TIER 4: HISTORICAL ARCHIVE (Load Rarely) +# ============================================ +# +# Active History: @doc/COMPLETED.md +# Debugging Docs: @cnn_v1/docs/CNN_DEBUG.md +# Archived Docs: @doc/archive/* +# +# Past Investigations: +# @cnn_v1/docs/CNN_BIAS_FIX_2026-02.md +# @cnn_v1/docs/CNN_FLATTEN_ANALYSIS.md +# @cnn_v1/docs/CNN_RGBD_GRAYSCALE_SUMMARY.md # ============================================ # PROJECT RULES (IMPORTANT) # ============================================ IMPORTANT: -- Follow all rules in doc/AI_RULES.md +- Follow all rules in @doc/AI_RULES.md - This repository is shared with Gemini-CLI - You are working in turns with another AI agent - Work only on tasks explicitly requested by the user @@ -40,7 +55,7 @@ IMPORTANT: - Max 100 tokens per reply # Context Maintenance: -- See doc/CONTEXT_MAINTENANCE.md for keeping context clean -- Archive completed work to doc/COMPLETED.md regularly +- See @doc/CONTEXT_MAINTENANCE.md for keeping context clean +- Archive completed work to @doc/COMPLETED.md regularly - Keep PROJECT_CONTEXT.md focused on current status - Keep TODO.md focused on active/next tasks only diff --git a/GEMINI.md b/GEMINI.md index 5c47b07..25e92a7 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -14,61 +14,37 @@ @doc/EFFECT_WORKFLOW.md # ============================================ -# TIER 3: DESIGN DOCS (Load On-Demand) +# TIER 3: DESIGN DOCS (Load On-Demand by Subsystem) # ============================================ -# Load these only when working on specific subsystems: # -# Audio & Tracker: -# doc/SPECTRAL_BRUSH_EDITOR.md - Spectral editor design -# doc/TRACKER.md - Audio tracker system -# -# 3D & Graphics: -# doc/3D.md - 3D rendering architecture -# doc/PROCEDURAL.md - Procedural generation -# -# Build & Assets: -# doc/ASSET_SYSTEM.md - Asset pipeline details -# doc/BUILD.md - Build system details -# doc/FETCH_DEPS.md - Dependency management -# -# Testing & Tools: -# doc/test_demo_README.md - test_demo tool documentation -# -# Architecture & Reference: -# doc/ARCHITECTURE.md - Detailed system architecture -# doc/CODING_STYLE.md - Code style examples -# doc/BACKLOG.md - Untriaged future goals -# doc/TOOLS_REFERENCE.md - Developer tools reference +# Audio: @doc/SPECTRAL_BRUSH_EDITOR.md, @doc/TRACKER.md, @doc/BEAT_TIMING.md +# CNN: @cnn_v1/docs/CNN_V1_EFFECT.md, @cnn_v2/docs/CNN_V2.md, @cnn_v2/docs/CNN_V2_BINARY_FORMAT.md +# 3D/Graphics: @doc/3D.md, @doc/GPU_PROCEDURAL_PHASE4.md, @doc/MASKING_SYSTEM.md, @doc/SDF_EFFECT_GUIDE.md +# Scene: @doc/SCENE_FORMAT.md, @doc/SEQUENCE.md, @doc/WORKSPACE_SYSTEM.md +# Build: @doc/ASSET_SYSTEM.md, @doc/BUILD.md, @doc/CMAKE_MODULES.md, @doc/SIZE_MEASUREMENT.md +# Rendering: @doc/GEOM_BUFFER.md, @doc/SHADER_REUSE_INVESTIGATION.md, @doc/UNIFORM_BUFFER_GUIDELINES.md, @doc/WGPU_HELPERS.md, @doc/AUXILIARY_TEXTURE_INIT.md +# Tools: @doc/test_demo_README.md, @doc/HOT_RELOAD.md, @doc/HEADLESS_MODE.md, @doc/RECIPE.md, @doc/TOOLS_REFERENCE.md +# Arch: @doc/ARCHITECTURE.md, @doc/CODING_STYLE.md, @doc/BACKLOG.md, @doc/CONTEXT_MAINTENANCE.md # ============================================ # TIER 4: HISTORICAL ARCHIVE (Load Rarely) # ============================================ -# Load these only for historical context or debugging: -# -# Completion History: -# Use: "read @doc/COMPLETED.md" for detailed history -# -# Technical Investigations: -# doc/GPU_EFFECTS_TEST_ANALYSIS.md -# doc/PLATFORM_ANALYSIS.md -# doc/PLATFORM_SIDE_QUEST_SUMMARY.md -# doc/PEAK_FIX_SUMMARY.md -# doc/CNN_DEBUG.md - CNN post-processing binding bug resolution # -# Agent Handoffs: -# doc/HANDOFF_CLAUDE.md -# doc/HANDOFF.md -# doc/HANDOFF_2026-02-04.md +# Active History: @doc/COMPLETED.md +# Debugging Docs: @cnn_v1/docs/CNN_DEBUG.md +# Archived Docs: @doc/archive/* # -# Task Tracking: -# doc/TASKS_SUMMARY.md +# Past Investigations: +# @cnn_v1/docs/CNN_BIAS_FIX_2026-02.md +# @cnn_v1/docs/CNN_FLATTEN_ANALYSIS.md +# @cnn_v1/docs/CNN_RGBD_GRAYSCALE_SUMMARY.md # ============================================ # PROJECT RULES (IMPORTANT) # ============================================ IMPORTANT: -- Follow all rules in doc/AI_RULES.md +- Follow all rules in @doc/AI_RULES.md - This repository is shared with Claude-Code - You are working in turns with another AI agent - Work only on tasks explicitly requested by the user @@ -80,7 +56,7 @@ IMPORTANT: # Context Maintenance: - See @doc/CONTEXT_MAINTENANCE.md for keeping context clean -- Archive completed work to doc/COMPLETED.md regularly +- Archive completed work to @doc/COMPLETED.md regularly - Keep PROJECT_CONTEXT.md focused on current status - Keep TODO.md focused on active/next tasks only @@ -95,7 +71,7 @@ IMPORTANT: ## Technical Preferences - **C++ Standards:** Default to C++20/C++23 unless specified otherwise. - **Style:** Prefer Modern C++ (RAII, templates, constexpr, STL) over C-style patterns. -- **Nomenclature:** Use standard engineering terminology (e.g., "O(n) complexity," "pointer aliasing," "cache miss") without defining the terms. +-Nomenclature:** Use standard engineering terminology (e.g., "O(n) complexity," "pointer aliasing," "cache miss") without defining the terms. ## Interaction Protocol - If a query is ambiguous, provide the most likely technical solution rather than asking for clarification. -- cgit v1.2.3