Skip to content

docs: restructure agent guidance with progressive disclosure - #112

Open
Fanduzi wants to merge 3 commits into
mainfrom
docs/agent-guidance
Open

Fanduzi wants to merge 3 commits into
mainfrom
docs/agent-guidance

Conversation

@Fanduzi

@Fanduzi Fanduzi commented Oct 14, 2026

Copy link
Copy Markdown
Owner

Summary

CLAUDE.md (1-line compatibility pointer)
└── AGENTS.md (12-line task router)
    ├── CODING_STANDARDS.md (42 lines; conditional sections)
    │   ├── Decisions and reporting
    │   ├── Changes and verification
    │   ├── Milestones
    │   ├── Delivery
    │   └── Release handoffs
    └── docs/agents/{domain,issue-tracker,triage-labels}.md (unchanged)

Three sequential subagents produced three increasingly structural commits:

  1. 9fde8058: prune generic defaults, discoverable command caches, and duplicated guidance; establish one authority.
  2. 64406d70: move operational instructions into CODING_STANDARDS.md behind conditional pointers.
  3. 0fa922d0: collapse overlapping routes, co-locate requirements, and reduce the compatibility bridge to one line.

With explicit user approval, remove only the two root guidance ignore entries so both documents are shared. No runtime code changes. No decision record required: this is one documentation-restructuring task, not a product milestone or a new architecture/public-contract boundary.

Evidence

  • Before: user-supplied local AGENTS.md and CLAUDE.md contained 71 + 108 lines; both were ignored and absent from main.
    After: root guidance contains 12 + 1 lines, with 42 lines of disclosed standards. Git therefore shows new tracked documents, not deletions from the supplied local baseline.
  • Checks at 0fa922d062361add8a3cb9f01ee2dfb4292fdef6: make test and git diff --check main...HEAD passed. Go package test results were cached.
  • Manually checked every edited-document link/anchor and traced ten task routes: explanation/domain, docs-only edits, rule/parser changes, PostgreSQL metadata, Node launcher, issue triage, milestones/parallel worktrees, commits/PRs, push/tag/release, and release handoffs.
  • Preserved ADR triggers/reporting, architectural ownership, module/bilingual documentation obligations, verification routes, milestone discipline, explicit publication authorization, and skill-first release handoffs.
  • git diff --name-only main...HEAD: .gitignore, AGENTS.md, CLAUDE.md, CODING_STANDARDS.md only. Candidate worktree is clean; original milestone worktree was not edited.

Merge Danger

Door: two-way

Documentation-only and reversible. The newly tracked guidance may interact with existing ignored local copies; preserve and reconcile those copies when adopting the branch.

Blast Radius: agents

Changes guidance discovery for coding agents, not SQL auditing behavior. Branch routing was reviewed manually; identical behavior across models is not claimed.

@coderabbitai

coderabbitai Bot commented Oct 14, 2026

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 18106169-ed8b-4434-8d34-141586922e04
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying deltascope with  Cloudflare Pages  Cloudflare Pages

Latest commit: 0fa922d
Status: ✅  Deploy successful!
Preview URL: https://f6320368.deltascope.pages.dev
Branch Preview URL: https://docs-agent-guidance.deltascope.pages.dev

View logs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant