[PR #251] [MERGED] chore(docs): revise agent guide

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/251 **Author:** [@yingdi-shan](https://github.com/yingdi-shan) **Created:** 9/7/2026 **Status:** ✅ Merged **Merged:** 9/7/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `docs/agent-guide-conventions` --- ### 📝 Commits (1) - [`51f0051`](https://github.com/kvcache-ai/AgentENV/commit/51f0051ed3ed33461bedf4b4bdebd769b8cd544a) chore(docs): revise agent guide and require contribution templates ### 📊 Changes **1 file changed** (+214 additions, -121 deletions) <details> <summary>View changed files</summary> 📝 `CLAUDE.md` (+214 -121) </details> ### 📄 Description ## What Revise the shared `CLAUDE.md` / `AGENTS.md` guide with behavioral guidelines, concise project concepts, validation commands, a code map, and key ownership constraints. Require PRs and issues to use the repository templates, including submissions created through the CLI. ## Why The existing guide mixes contribution instructions with extensive architecture detail and outdated test/setup guidance. A focused guide makes the expected workflow and important snapshot, volume, OSS, and OverlayBD distinctions easier to find. ## Related issue None. This is a scoped documentation improvement. ## Scope and non-goals Only `CLAUDE.md` changes. The existing `AGENTS.md` symlink continues to read the same guide. Runtime code, contribution templates, and configuration are outside this change. ## Design and behavior changes - Define four behavioral principles: think before coding, simplicity first, surgical changes, and goal-driven execution. - Condense project guidance and link to detailed documentation while retaining lifecycle, storage, volume, P2P, and extension constraints. - Align test instructions with the capability runner and distinguish host setup from dependency provisioning. - Require the PR template and the appropriate issue form, with required sections completed and checks reported accurately. ## Compatibility and operations - Public API or generated protocol: N/A; documentation only. - Configuration or defaults: N/A; no configuration changes. - Snapshot manifest, artifact layout, or storage format: N/A; existing contracts are documented. - Upgrade and rollback: No deployment required; revert the documentation commit to roll back. - Host requirements, permissions, ports, or dependencies: No changes; the guide describes existing prerequisites. ## Validation - [ ] `make fmt` - [ ] `make clippy` - [ ] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text git diff --check Passed git diff --name-only origin/main CLAUDE.md only readlink AGENTS.md CLAUDE.md ``` A local Node.js audit verified all 18 local links, 43 repository paths, 15 Make commands, the symlink contents, and balanced code fences. Behavioral guidance was also checked against the preserved full version. Skipped checks and reasons: Rust/Go builds, runtime tests, code generation, and benchmarks were not run because this changes only Markdown instructions. ## Risks and reviewer notes Review the behavioral guidance and project constraints for instruction accuracy. Referenced commands were checked against the current Makefiles; no runtime behavior changes. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi commented

2026-10-29 14:21:53 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/251
Author: @yingdi-shan
Created: 9/7/2026
Status: ✅ Merged
Merged: 9/7/2026
Merged by: @yingdi-shan

Base: main ← Head: docs/agent-guide-conventions

📝 Commits (1)

51f0051 chore(docs): revise agent guide and require contribution templates

📊 Changes

1 file changed (+214 additions, -121 deletions)

View changed files

📝 CLAUDE.md (+214 -121)

📄 Description

What

Revise the shared CLAUDE.md / AGENTS.md guide with behavioral guidelines, concise project concepts, validation commands, a code map, and key ownership constraints. Require PRs and issues to use the repository templates, including submissions created through the CLI.

Why

The existing guide mixes contribution instructions with extensive architecture detail and outdated test/setup guidance. A focused guide makes the expected workflow and important snapshot, volume, OSS, and OverlayBD distinctions easier to find.

None. This is a scoped documentation improvement.

Scope and non-goals

Only CLAUDE.md changes. The existing AGENTS.md symlink continues to read the same guide. Runtime code, contribution templates, and configuration are outside this change.

Design and behavior changes

Define four behavioral principles: think before coding, simplicity first, surgical changes, and goal-driven execution.
Condense project guidance and link to detailed documentation while retaining lifecycle, storage, volume, P2P, and extension constraints.
Align test instructions with the capability runner and distinguish host setup from dependency provisioning.
Require the PR template and the appropriate issue form, with required sections completed and checks reported accurately.

Compatibility and operations

Public API or generated protocol: N/A; documentation only.
Configuration or defaults: N/A; no configuration changes.
Snapshot manifest, artifact layout, or storage format: N/A; existing contracts are documented.
Upgrade and rollback: No deployment required; revert the documentation commit to roll back.
Host requirements, permissions, ports, or dependencies: No changes; the guide describes existing prerequisites.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

git diff --check                 Passed
git diff --name-only origin/main CLAUDE.md only
readlink AGENTS.md               CLAUDE.md

A local Node.js audit verified all 18 local links, 43 repository paths, 15 Make commands, the symlink contents, and balanced code fences. Behavioral guidance was also checked against the preserved full version.

Skipped checks and reasons:

Rust/Go builds, runtime tests, code generation, and benchmarks were not run because this changes only Markdown instructions.

Risks and reviewer notes

Review the behavioral guidance and project constraints for instruction accuracy. Referenced commands were checked against the current Makefiles; no runtime behavior changes.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

bsakaguchi

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-10-29 14:22:13 +00:00

[PR #292] [MERGED] fix(cli): reliably fall back to sh when bash is unavailable #325

Rows
Columns

[PR #251] [MERGED] chore(docs): revise agent guide #292