Update repository agent guidance#43
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary
This PR creates AGENTS.md (a near-identical copy of CLAUDE.md) and adds a PR Hygiene principle to both files. The AGENTS.md file appears to be for "repository agent guidance" but lacks any explanation of its purpose or how it differs from CLAUDE.md. The documentation duplication creates a significant maintenance burden without clear benefit. REQUEST_CHANGES — the author should clarify why two separate agent guidance files are needed.
Blocking
- AGENTS.md:1–94 — Duplicate documentation file without clear purpose. AGENTS.md is nearly identical to CLAUDE.md (only the self-references differ: "AGENTS.md" vs "CLAUDE.md" in lines 3, 7, and 55). Any future update to project guidance must now be synchronized across two files, doubling maintenance effort and creating drift risk. The PR description says "add AGENTS.md as repo-level agent guidance" but provides no rationale for why this needs to be a separate file, what agent system consumes it, or how it differs from CLAUDE.md.
Questions
- Why does this repo need both AGENTS.md and CLAUDE.md? What agent consumes AGENTS.md, and why can't it use CLAUDE.md directly?
- Is AGENTS.md intended to be a symlink to CLAUDE.md (avoiding duplication), or a true separate file with different content planned?
- If AGENTS.md is for a different agent system, should it reference CLAUDE.md (e.g., "See CLAUDE.md for the authoritative guidance") rather than duplicating?
Verified
- Self-references: Confirmed AGENTS.md refers to itself (lines 3, 7, 55) while CLAUDE.md refers to itself — not a symlink issue.
- Content parity: AGENTS.md matches CLAUDE.md word-for-word except for the self-references and AGENTS.md lacks the
currentDatesection. - PR Hygiene principle: Good addition — addresses a real security/privacy concern about leaking internal details.
🤖 Reviewed by vivi • workflow run
Avoids drift from maintaining two near-identical files. CLAUDE.md remains the single source of truth; AGENTS.md exists as a symlink so agent harnesses that probe for AGENTS.md (e.g. OpenAI codex) still find the guidance.
There was a problem hiding this comment.
Based on my complete review, let me now write the review summary.
Summary
This PR adds AGENTS.md as a symlink to CLAUDE.md to support agent harnesses that look for AGENTS.md (e.g., OpenAI Codex), while keeping CLAUDE.md as the single source of truth. The change also removes Chinese characters from the Occam's Razor principle and adds a new "PR Hygiene" principle about not leaking internal details. The symlink approach is appropriate given the project only targets Linux and macOS (no Windows builds). APPROVE — this is a clean documentation change with clear intent and correct implementation.
Verified
- Symlink correctness:
AGENTS.md -> CLAUDE.mdresolves correctly and git tracks it as a symlink (mode 120000) - Content accuracy: Repository structure diagram matches actual layout (already missing
ts-pcap-extractanddeploy/before this PR) - Cross-platform compatibility: Release builds target Linux/macOS only (no Windows), so symlink portability is not a concern
- Whitespace: No trailing whitespace or other formatting issues
- Commit alignment: Both commits match their stated intent — "Update repository agent guidance" creates AGENTS.md, "Make AGENTS.md a symlink" converts it to symlink
- Single source of truth: Content reads correctly via symlink and matches CLAUDE.md exactly
🤖 Reviewed by vivi • workflow run
1 participant
Summary:
Validation: