Add AGENT.md, CLAUDE.md symlink, and pre-push git hook by simianhacker · Pull Request #156 · elastic/semantic-code-search-indexer

simianhacker · 2026-03-19T22:25:06Z

Summary

Adds comprehensive agent documentation and strengthens the git hook safety net.

Changes

AGENT.md — Comprehensive guide for AI coding agents covering:
- Project architecture and data flow
- All verification commands (build, test, lint, format)
- Git hook documentation (pre-commit + pre-push)
- Test conventions and patterns
- Code style and formatting rules
- Language system and how to add new languages
- Common patterns (ES client, logging, metrics, error handling)
- Important gotchas and caveats
CLAUDE.md — Symlink to AGENT.md (Claude Code convention)
.husky/pre-push — New hook running build → test → lint → format:check as a safety net to block broken pushes, even if pre-commit was bypassed with --no-verify
.husky/pre-commit — Added format:check to the existing hook (was previously missing formatting verification)

- AGENT.md: comprehensive agent guide covering architecture, data flow, verification commands, test conventions, code style, language system, common patterns, and gotchas - CLAUDE.md: symlink to AGENT.md - .husky/pre-push: new hook running build/test/lint/format:check as a safety net to block broken pushes - .husky/pre-commit: add format:check to existing hook

coderabbitai · 2026-03-19T22:27:43Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6d26d2b0-f486-4606-82a0-5872076ba569

📥 Commits

Reviewing files that changed from the base of the PR and between f1ffbfd and 2fad3cb.

📒 Files selected for processing (1)

AGENT.md

📝 Walkthrough

Walkthrough

This change updates Git hooks and adds documentation and ignore rules. The pre-commit hook now runs npm run format:check after npm run build, npm run test, and npm run lint, and its message was updated. A new .husky/pre-push hook was added that runs npm run build && npm run test && npm run lint && npm run format:check. Added AGENT.md (detailed Semantic Code Search Indexer guide) and CLAUDE.md (minimal file). .gitignore updated to ignore .cursor.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding AGENT.md documentation, CLAUDE.md symlink, and the new pre-push git hook.
Description check	✅ Passed	The description is directly related to the changeset, providing clear details about each file added and modified (AGENT.md, CLAUDE.md, pre-push, pre-commit).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📝 Coding Plan

Generate coding plan for human review comments

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

coderabbitai

Actionable comments posted: 2

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ed4add8c-69fe-4746-8d89-299eb7194739

📥 Commits

Reviewing files that changed from the base of the PR and between 6883198 and 6d2db27.

📒 Files selected for processing (4)

.husky/pre-commit
.husky/pre-push
AGENT.md
CLAUDE.md

AGENT.md

Copilot

Pull request overview

Adds an agent-oriented guide for working in the Semantic Code Search Indexer repo and strengthens local safety checks by expanding Husky hooks to include formatting checks and a new pre-push gate.

Changes:

Added AGENT.md documenting architecture, verification commands, test conventions, formatting/linting rules, and operational gotchas.
Added CLAUDE.md as a symlink to AGENT.md for Claude Code compatibility.
Updated Husky hooks: pre-commit now includes format:check, and added a new pre-push hook running build → test → lint → format:check.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
AGENT.md	New agent guide documenting repo architecture, workflows, and conventions
CLAUDE.md	Symlink to agent guide (Claude convention)
.husky/pre-push	New hook to block pushes when build/tests/lint/format checks fail
.husky/pre-commit	Adds `format:check` to existing pre-commit verification

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AGENT.md

- Add 'text' language specifier to architecture code block (CodeRabbit) - Add blank line before logging code block (CodeRabbit) - Fix Husky bypass wording to include HUSKY=0 (Copilot) - Fix .prettierrc → .prettierrc.json filename (Copilot) - Fix scaffold command to use actual scaffold-language CLI (Copilot)

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 06e8862a-fc20-4ebb-87c7-f421dbfc8fb5

📥 Commits

Reviewing files that changed from the base of the PR and between 6d2db27 and 2f6777c.

📒 Files selected for processing (1)

AGENT.md

AGENT.md

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-19T23:50:59Z

.husky/pre-push

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"


Both hooks source .husky/_/husky.sh, but that file/directory doesn't exist in the repo right now. This causes a "not found" error on every hook run and also means Husky features like HUSKY=0 bypass may not work. Please either commit Husky’s ./.husky/_/husky.sh (and related files) or remove the sourcing line and implement the needed bypass logic directly in the hook scripts.

Suggested change

. "$(dirname -- "$0")/_/husky.sh"

# Allow bypassing this hook by setting HUSKY=0, similar to husky.sh

if [ "${HUSKY:-1}" = "0" ]; then

exit 0

fi

Copilot · 2026-03-19T23:50:59Z

.husky/pre-commit

 . "$(dirname -- "$0")/_/husky.sh"



This hook sources .husky/_/husky.sh, but that path isn’t present in the repository. This will emit a shell error on every commit and may break HUSKY=0 bypass behavior. Consider committing the Husky ./.husky/_ helper files or inlining the minimal logic (including honoring HUSKY=0) and removing the source line.

Suggested change

. "$(dirname -- "$0")/_/husky.sh"

# Honor Husky's HUSKY=0 bypass: skip the hook when explicitly disabled.

if [ "${HUSKY-}" = "0" ]; then

exit 0

fi

# Run from the repository root when possible, for consistent behavior.

if command -v git >/dev/null 2>&1; then

cd -- "$(git rev-parse --show-toplevel)" || exit 0

fi

kapral18 · 2026-03-20T02:26:16Z

AGENT.md

should be AGENTS.md instead of AGENT.md

maybe this is the reason sonnet is not listening

kapral18 · 2026-03-20T02:52:32Z

AGENT.md

+## Git Hooks (Husky)
+
+> **🚨 CRITICAL: NEVER bypass Husky hooks.** Do not use `--no-verify`, `HUSKY=0`, or any
+> other mechanism to skip hooks. No exceptions. If a hook fails, **fix the issue** — do not
+> work around the hook. Broken code must never be committed or pushed. This is a hard rule.
+
+Two hooks gate every commit and push:
+
+| Hook | Runs | Purpose |
+|------|------|---------|
+| **pre-commit** | `build → test → lint → format:check` | Catches errors before they enter history |
+| **pre-push** | `build → test → lint → format:check` | Safety net — blocks pushes even if commit hooks were skipped |
+
+Both hooks run the same four checks. If any step fails, the operation is aborted.


I think this is better in personal agent hooks actually enforced for dumb models

kapral18 · 2026-03-20T02:56:48Z

AGENT.md

also honestly I'd remove almost all overview/architectural guidance everything. Almost all of it is inferrable by agent. I would only leave a couple of commands and instructions when to use them that's it ultra thin.

And the overview thing we can add a marble diagram to compress the data for agents.

Wdyt?

Copilot AI review requested due to automatic review settings March 19, 2026 22:25

Copilot started reviewing on behalf of simianhacker March 19, 2026 22:25 View session

coderabbitai bot requested changes Mar 19, 2026

View reviewed changes

AGENT.md Outdated Show resolved Hide resolved

AGENT.md Show resolved Hide resolved

Copilot AI reviewed Mar 19, 2026

View reviewed changes

AGENT.md Outdated Show resolved Hide resolved

AGENT.md Outdated Show resolved Hide resolved

AGENT.md Outdated Show resolved Hide resolved

coderabbitai bot requested changes Mar 19, 2026

View reviewed changes

AGENT.md Show resolved Hide resolved

Add .cursor to .gitignore

f1ffbfd

Copilot AI review requested due to automatic review settings March 19, 2026 23:46

Copilot started reviewing on behalf of simianhacker March 19, 2026 23:46 View session

coderabbitai bot approved these changes Mar 19, 2026

View reviewed changes

Copilot AI reviewed Mar 19, 2026

View reviewed changes

Add explicit rule: NEVER bypass Husky hooks

2fad3cb

kapral18 reviewed Mar 20, 2026

View reviewed changes

simianhacker closed this Apr 7, 2026

		@@ -0,0 +1,5 @@
		#!/usr/bin/env sh
		. "$(dirname -- "$0")/_/husky.sh"

-. "$(dirname -- "$0")/_/husky.sh"
+# Allow bypassing this hook by setting HUSKY=0, similar to husky.sh
+if [ "${HUSKY:-1}" = "0" ]; then
+  exit 0
+fi

-. "$(dirname -- "$0")/_/husky.sh"
+# Honor Husky's HUSKY=0 bypass: skip the hook when explicitly disabled.
+if [ "${HUSKY-}" = "0" ]; then
+  exit 0
+fi
+# Run from the repository root when possible, for consistent behavior.
+if command -v git >/dev/null 2>&1; then
+  cd -- "$(git rev-parse --show-toplevel)" || exit 0
+fi

Conversation

simianhacker commented Mar 19, 2026

Summary

Changes

Uh oh!

coderabbitai bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

kapral18 Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kapral18 Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

kapral18 Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai bot commented Mar 19, 2026 •

edited

Loading

kapral18 Mar 20, 2026 •

edited

Loading