general: T8595: add CLAUDE.md

[andamasov]

Summary

Adds a single source of truth for repo-level agent instructions, plus three symlinks so different agentic tools all read the same content from one canonical file.

Files added:

Path	Type	Consumed by
CLAUDE.md	real file	Claude Code, Anthropic agents
AGENTS.md	symlink → CLAUDE.md	tools that follow the AGENTS.md convention (e.g. OpenAI Codex)
.cursorrules	symlink → CLAUDE.md	Cursor
.github/copilot-instructions.md	symlink → ../CLAUDE.md	GitHub Copilot (docs)

Rationale

• One source of truth — guidance lives in CLAUDE.md, the symlinks are zero-content. No drift between four files.
• Each agentic tool reads its canonical filename and gets the same content.
• Mac/Linux dev environments handle symlinks natively. Windows checkouts may render them as text files containing the target path; the canonical CLAUDE.md is unaffected and still rendered/served correctly by GitHub.

Out of scope

Path-specific Copilot instructions (.github/instructions/*.instructions.md) need YAML frontmatter (applyTo:) and target specific globs, so they cannot be symlinks. Not added here; they can be authored as separate small files per-repo if/when narrow path-scoped guidance is needed.

Tracked under T8595.

Test plan

• CLAUDE.md renders on GitHub.
• AGENTS.md, .cursorrules, .github/copilot-instructions.md resolve to CLAUDE.md content (readlink returns the right target).
• CI passes.

🤖 Generated by robots

[coderabbitai]

Warning

Rate limit exceeded

@andamasov has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minute and 49 seconds before requesting another review.

To continue reviewing without waiting, purchase usage credits in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 87892fe7-2fe9-412a-9a63-5903b32c7f3e

📥 Commits

Reviewing files that changed from the base of the PR and between ef69652 and c49e98e.

📒 Files selected for processing (3)

• .github/copilot-instructions.md
• AGENTS.md
• CLAUDE.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch T8595-add-claude-md

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch T8595-add-claude-md

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[andamasov]

@copilot review

[andamasov]

@copilot review

[Copilot]

@copilot review

Review summary — documentation only, no code changes

All technical claims in CLAUDE.md were verified against the source tree:

• passwd field forced to 'x' ✔ (confirmed in map_common.c and README)
• NSS module ordering (libnss_mapuid first, libnss_mapname last) ✔ (matches README)
• Repository layout, build commands, and package name ✔ (match Makefile / debian/control)

No issues found. The internal Confluence link that was in the original draft has been removed in the follow-up commit (d581bb9). The file is accurate, uses standard UTF-8 encoding, and introduces no security concerns. Good to merge.

[Copilot]

@copilot review

No changes have been made since the previous review. The earlier summary still stands — all technical claims in CLAUDE.md are accurate, the internal Confluence link has been removed (d581bb9), and there are no issues. Good to merge.

[andamasov]

@copilot review

[andamasov]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[andamasov]

Closing in favor of vyos/libnss-mapuser#16 under T8595.

Schema changed: AGENTS.md is now the tool-neutral primary instructions file. .github/copilot-instructions.md is a symlink to ../AGENTS.md (verified working with Copilot code review). No CLAUDE.md, no .cursorrules — both tools fall back to AGENTS.md natively.