|
2 | 2 |
|
3 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | 4 |
|
5 | | -## Auto-memory policy |
6 | | - |
7 | | -**Do NOT use MEMORY.md.** Claude Code's auto-memory feature stores behavioral |
8 | | -rules outside of version control, making them invisible to code review, |
9 | | -inconsistent across repos, and unreliable across sessions. All behavioral rules, |
10 | | -conventions, and workflow instructions belong in managed, version-controlled |
11 | | -documentation (CLAUDE.md, AGENTS.md, skills, or docs/). |
12 | | - |
13 | | -If you identify a pattern, convention, or rule worth preserving: |
14 | | - |
15 | | -1. **Stop.** Do not write to MEMORY.md. |
16 | | -2. **Discuss with the user** what you want to capture and why. |
17 | | -3. **Together, decide** the correct managed location (CLAUDE.md, a skill file, |
18 | | - standards docs, or a new issue to track the gap). |
19 | | - |
20 | | -This policy exists because MEMORY.md is per-directory and per-machine — it |
21 | | -creates divergent agent behavior across the multi-repo environment this project |
22 | | -operates in. Consistency requires all guidance to live in shared, reviewable |
23 | | -documentation. |
24 | | - |
25 | | -## Shell command policy |
26 | | - |
27 | | -**Do NOT use heredocs** (`<<EOF` / `<<'EOF'`) for multi-line arguments to CLI |
28 | | -tools such as `gh`, `git commit`, or `curl`. Heredocs routinely fail due to |
29 | | -shell escaping issues with apostrophes, backticks, and special characters. |
30 | | -Always write multi-line content to a temporary file and pass it via `--body-file` |
31 | | -or `--file` instead. |
32 | | - |
33 | | -## Documentation Strategy |
34 | | - |
35 | | -This repository uses two complementary approaches for AI agent guidance: |
36 | | - |
37 | | -- **AGENTS.md**: Generic AI agent instructions using include directives to force documentation indexing. Contains canonical standards references, shared skills loading, and user override support. |
38 | | -- **CLAUDE.md** (this file): Claude Code-specific guidance with prescriptive commands, architecture details, and development workflows optimized for `/init`. |
39 | | - |
40 | | -### Integration Approach |
41 | | - |
42 | | -**For Claude Code** (`/init` command): |
43 | | -1. Read CLAUDE.md (this file) first for optimized quick-start guidance |
44 | | -2. Process include directives to load repository standards |
45 | | -3. Reference AGENTS.md for shared skills and canonical standards location |
46 | | -4. Apply layered standards: canonical → project-specific → user overrides |
47 | | - |
48 | | -**For other AI agents** (Codex, generic LLMs): |
49 | | -1. Read AGENTS.md first as the primary entry point |
50 | | -2. Process include directives to load all referenced documentation |
51 | | -3. Resolve canonical standards repo path (local or GitHub) |
52 | | -4. Load shared skills from standards repo |
53 | | -5. Apply user overrides from `~/AGENTS.md` if present |
54 | | - |
55 | | -**Key differences**: |
56 | | -- **CLAUDE.md**: Prescriptive, command-focused, optimized for `/init` |
57 | | -- **AGENTS.md**: Declarative, include-directive-driven, forces full documentation indexing |
58 | | - |
59 | | -Both files share the same underlying standards via include directives, ensuring consistency across all AI agents working in this repository. |
60 | | - |
61 | | -### Best Practices for Dual-File Approach |
62 | | - |
63 | | -**What goes in AGENTS.md**: |
64 | | -- Include directives for documentation indexing |
65 | | -- Canonical standards repository references |
66 | | -- Shared skills loading instructions |
67 | | -- User override mechanisms |
68 | | -- Minimal, declarative content |
69 | | - |
70 | | -**What goes in CLAUDE.md**: |
71 | | -- Claude Code-specific quick-start commands |
72 | | -- Detailed architecture and design patterns |
73 | | -- Implementation notes and common workflows |
74 | | -- Integration guidance between the two files |
75 | | -- More verbose, prescriptive content |
76 | | - |
77 | | -**What goes in neither (use includes instead)**: |
78 | | -- Repository standards (keep in `docs/repository-standards.md`) |
79 | | -- Canonical standards (reference external repo) |
80 | | -- Project-specific conventions (keep in referenced docs) |
81 | | - |
82 | | -**Maintenance strategy**: |
83 | | -- Update standards in source files, not in AGENTS.md or CLAUDE.md |
84 | | -- Use include directives to pull in shared content |
85 | | -- Keep AGENTS.md minimal and CLAUDE.md focused on Claude Code workflows |
86 | | -- Test both entry points when updating documentation structure |
87 | | - |
88 | 5 | <!-- include: docs/standards-and-conventions.md --> |
89 | 6 | <!-- include: docs/repository-standards.md --> |
90 | 7 |
|
@@ -309,25 +226,6 @@ in mq-rest-admin-common for the full cross-language map. |
309 | 226 | - `src/pymqrest/commands.py` is generated (methods omit per-method docstrings per ruff config) |
310 | 227 | - Generation scripts in `scripts/dev/` regenerate code from `MAPPING_DATA` |
311 | 228 |
|
312 | | -## Repository Standards Quick Reference |
313 | | - |
314 | | -The include directives at the top of this file load the full repository standards. Key highlights for quick reference: |
315 | | - |
316 | | -**Pre-flight Checklist**: |
317 | | -- Check current branch: `git status -sb` |
318 | | -- If on `develop`, create `feature/*` branch or get explicit approval |
319 | | -- Enable git hooks: `git config core.hooksPath ../standard-tooling/scripts/lib/git-hooks` |
320 | | - |
321 | | -**Python Invocation**: Always use `uv run python3 <script>` |
322 | | - |
323 | | -**Tooling**: `uv` version `0.10.4` |
324 | | - |
325 | | -**Code Quality**: Ruff (all rules), mypy (strict), 100% test coverage, Python 3.14+ |
326 | | - |
327 | | -**Repository Profile**: library, library-release branching, artifact-publishing |
328 | | - |
329 | | -See `docs/repository-standards.md` for complete details. |
330 | | - |
331 | 229 | ## Important Implementation Notes |
332 | 230 |
|
333 | 231 | ### MQSC Command Execution |
@@ -362,80 +260,13 @@ Mapping can be disabled per-session or per-call with `map_attributes=False`. |
362 | 260 | - `DEFINE` and `DELETE` methods raise on errors |
363 | 261 | - Error payloads stored on session for diagnostics |
364 | 262 |
|
365 | | -## Documentation Indexing Strategy |
366 | | - |
367 | | -This repository uses `<!-- include: path/to/file.md -->` directives to force documentation indexing. When you encounter these directives: |
368 | | - |
369 | | -1. **Read the referenced files** to understand the full context |
370 | | -2. **Apply layered standards** in order: |
371 | | - - Canonical standards (from `standards-and-conventions` repo) |
372 | | - - Project-specific standards (`docs/repository-standards.md`) |
373 | | - - User overrides (`~/AGENTS.md` if present) |
374 | | -3. **Load shared skills** from `<standards-repo-path>/skills/**/SKILL.md` |
375 | | - |
376 | | -The include directives appear in: |
377 | | -- `AGENTS.md` - Includes repository standards and conventions |
378 | | -- `CLAUDE.md` - Includes same standards for Claude Code |
379 | | -- `docs/standards-and-conventions.md` - Includes canonical standards reference |
380 | | - |
381 | | -This approach ensures all AI agents (Codex, Claude, etc.) have access to the same foundational documentation. |
382 | | - |
383 | | -## Documentation Structure |
384 | | - |
385 | | -- `README.md` - Project overview and quick start |
386 | | -- `AGENTS.md` - Generic AI agent instructions with include directives |
387 | | -- `CLAUDE.md` - This file, Claude Code-specific guidance |
388 | | -- `docs/mq-rest-wrapper-design.md` - Detailed design document |
389 | | -- `docs/mq-container-local-dev.md` - Local development with MQ container |
390 | | -- `docs/repository-standards.md` - Project-specific standards (included from AGENTS.md) |
391 | | -- `docs/standards-and-conventions.md` - Canonical standards reference (includes external repo) |
392 | | - |
393 | | -## Commit and PR Scripts |
394 | | - |
395 | | -**NEVER use raw `git commit`** — always use `st-commit`. |
396 | | -**NEVER use raw `gh pr create`** — always use `st-submit-pr`. |
397 | | - |
398 | | -### Committing |
399 | | - |
400 | | -```bash |
401 | | -st-commit --type feat --scope session --message "add retry logic" --agent claude |
402 | | -st-commit --type fix --message "correct attribute mapping" --agent claude |
403 | | -``` |
404 | | - |
405 | | -- `--type` (required): `feat|fix|docs|style|refactor|test|chore|ci|build` |
406 | | -- `--message` (required): commit description |
407 | | -- `--agent` (required): `claude` or `codex` — resolves the correct `Co-Authored-By` identity |
408 | | -- `--scope` (optional): conventional commit scope |
409 | | -- `--body` (optional): detailed commit body |
410 | | - |
411 | | -### Submitting PRs |
412 | | - |
413 | | -```bash |
414 | | -st-submit-pr --issue 42 --summary "Add retry logic to session" |
415 | | -st-submit-pr --issue 42 --linkage Ref --summary "Update docs" --docs-only |
416 | | -``` |
417 | | - |
418 | | -- `--issue` (required): GitHub issue number (just the number) |
419 | | -- `--summary` (required): one-line PR summary |
420 | | -- `--linkage` (optional, default: `Fixes`): `Fixes|Closes|Resolves|Ref` |
421 | | -- `--title` (optional): PR title (default: most recent commit subject) |
422 | | -- `--notes` (optional): additional notes |
423 | | -- `--docs-only` (optional): applies docs-only testing exception |
424 | | -- `--dry-run` (optional): print generated PR without executing |
425 | | - |
426 | 263 | ## Key References |
427 | 264 |
|
428 | | -**Canonical Standards**: https://github.com/wphillipmoore/standards-and-conventions |
429 | | -- Local path (preferred): `../standards-and-conventions` |
430 | | -- Load all skills from: `<standards-repo-path>/skills/**/SKILL.md` |
431 | | - |
432 | 265 | **External Documentation**: |
433 | 266 | - IBM MQ 9.4 administrative REST API |
434 | 267 | - MQSC command reference |
435 | 268 | - PCF command formats |
436 | 269 |
|
437 | | -**User Overrides**: `~/AGENTS.md` (optional, applied if present and readable) |
438 | | - |
439 | 270 | ## Temporary Workarounds |
440 | 271 |
|
441 | 272 | **Codex Branch Deletion**: The Codex execution harness may reject `git branch -d` even with `sandbox_mode = "danger-full-access"`. Workaround: use `git update-ref -d refs/heads/<branch>` when cleanup is required. |
0 commit comments