Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

docs: Add Working Model and Local Guidance Convention#2

Open
davidfsol5 wants to merge 1 commit into
main from
working-model-guidance
Open

docs: Add Working Model and Local Guidance Convention #2
davidfsol5 wants to merge 1 commit into
main from
working-model-guidance

Conversation

@davidfsol5

@davidfsol5 davidfsol5 commented Jun 4, 2026

Copy link
Copy Markdown
Member

Summary

Following the merge of PR #1 (polycentric-experiments), this PR codifies the conceptual insights derived from reviewing that work into the project's CLAUDE.md.

Working Model Section

Captures the evolving conceptual model of polycentric knowledge processing:

  • Polycentricity vs Distribution — Clarifies the distinction: heterogeneous instances with autonomous centers vs homogeneous instances with merged centers
  • The Seam — Shared referent IRIs that enable join across perspectives without collapsing them (common referents + perspective-scoped structures)
  • Sharing as Projection — The 4-field model (include_types, stub_types, edge_predicates, exclude_nodes) operating over any RDF vocabulary
  • Non-Collapse Invariant — Verification that perspectives remain distinct after merge/comparison
  • Operational Principles — Immutable input, reproducible experiments, heterogeneous deployment, "just enough" sharing

Local Guidance Convention Section

Establishes a two-tier guidance system for Claude Code:

  • Version-controlled: CLAUDE.md — authoritative, team-shared
  • Local: .claude/CLAUDE.md — working notes, gitignored, supplements (does not override)
  • Semantics: Scope, inheritance, and precedence rules
  • Coherence checks: On commit/PR with promotion path for mature insights

.gitignore Update

Changes .claude/ to **/.claude/ to support the convention that local guidance directories can exist at any level in the repo.

Context

This PR emerged from the review of PR #1, where we identified that mzargham's experiments implicitly refined several conceptual elements of the project's working model. Rather than leaving these insights uncodified, we're promoting them to the shared CLAUDE.md.

The Local Guidance Convention addresses the need for "engineering room" — a place for working models and observations before they're ready for team consumption.

Test Plan

  • Changes are documentation-only (no code changes)
  • .gitignore pattern tested: **/.claude/ correctly matches nested directories

Generated with Claude Code

Captures the evolving conceptual model of polycentric knowledge processing
refined through Experiments 1-3:
Working Model:
- Polycentricity vs Distribution distinction
- The Seam: shared referent IRIs enabling join without collapse
- Sharing as Projection: 4-field model (include_types, stub_types,
 edge_predicates, exclude_nodes)
- Non-Collapse Invariant: perspectives must remain distinct
- Operational principles: immutable input, reproducible experiments,
 heterogeneous deployment, "just enough" sharing
Local Guidance Convention:
- Two-tier system: version-controlled CLAUDE.md + local .claude/CLAUDE.md
- Semantics: scope, inheritance, precedence rules
- Coherence checks on commit/PR with promotion path
- Purpose: engineering room for working models before team consumption
Also updates .gitignore to use **/.claude/ pattern for nested directories.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
davidfsol5 pushed a commit that referenced this pull request Jun 4, 2026
Documents the session covering:
- PR #1 review and approval (polycentric-experiments)
- Working model analysis (7 conceptual refinements identified)
- Local Guidance Convention design discussion
- PR #1 merge
- PR #2 creation (working-model-guidance)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mzargham mzargham Awaiting requested review from mzargham

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

AltStyle によって変換されたページ (->オリジナル) /