Skip to content

Commit c858d41

Browse files
wphillipmoorewphillipmoore-claude
andauthored
chore(docs): strip CLAUDE.md boilerplate now covered by plugin (#439)
Removes sections now enforced by the standard-tooling plugin. Co-authored-by: wphillipmoore-claude <255925739+wphillipmoore-claude@users.noreply.github.com>
1 parent 46fe233 commit c858d41

1 file changed

Lines changed: 0 additions & 169 deletions

File tree

CLAUDE.md

Lines changed: 0 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -2,89 +2,6 @@
22

33
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44

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-
885
<!-- include: docs/standards-and-conventions.md -->
896
<!-- include: docs/repository-standards.md -->
907

@@ -309,25 +226,6 @@ in mq-rest-admin-common for the full cross-language map.
309226
- `src/pymqrest/commands.py` is generated (methods omit per-method docstrings per ruff config)
310227
- Generation scripts in `scripts/dev/` regenerate code from `MAPPING_DATA`
311228

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-
331229
## Important Implementation Notes
332230

333231
### MQSC Command Execution
@@ -362,80 +260,13 @@ Mapping can be disabled per-session or per-call with `map_attributes=False`.
362260
- `DEFINE` and `DELETE` methods raise on errors
363261
- Error payloads stored on session for diagnostics
364262

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-
426263
## Key References
427264

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-
432265
**External Documentation**:
433266
- IBM MQ 9.4 administrative REST API
434267
- MQSC command reference
435268
- PCF command formats
436269

437-
**User Overrides**: `~/AGENTS.md` (optional, applied if present and readable)
438-
439270
## Temporary Workarounds
440271

441272
**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

Comments
 (0)