投稿日: 投稿者: 1x2x3

Claude Max 5 / Claude Code: Best practices for agentic coding 1

Claude Codeを使った開発の効率を上げる準備です。(2025.09.25)

Claude Code: Best practices for agentic coding

上記の公式HPから日本語にして抜粋するだけです。

1. Customize your setup

あなたの目的に合わせて設定しろ。

1-1. Create CLAUDE.md files

CLAUDE.mdを作れ。

公式の内容がおそらく汎用的にするために抽象的なので、具体的な例をClaude Opus 4.1に提示してもらいます。

指示内容 : オープンソースを使ったロボット開発用のCLAUDE.mdの例を作成して新規ファイルとして保存してください。

英語で指示 : Create an example CLAUDE.md for robotics development using open source and save it as a new file.

CLAUDE.md

# Claude Configuration for Robotics Development

## Project Type
Open Source Robotics Development

## Development Environment
- **Operating System**: Ubuntu 22.04 LTS
- **ROS Version**: ROS 2 Humble
- **Python Version**: 3.10+
- **Build System**: colcon
- **Package Manager**: apt, pip, rosdep

## Key Technologies
- **Robotics Framework**: ROS 2 (Robot Operating System)
- **Simulation**: Gazebo, RViz2
- **Computer Vision**: OpenCV, PCL (Point Cloud Library)
- **Machine Learning**: PyTorch, TensorFlow, scikit-learn
- **Motion Planning**: MoveIt 2, Nav2
- **Hardware Interfaces**: ros2_control, micro-ROS
- **Communication**: DDS (Data Distribution Service)

## Common Commands

### Build and Test
```bash
# Build workspace
colcon build --symlink-install

# Run tests
colcon test

# Check test results
colcon test-result --verbose

# Install dependencies
rosdep install --from-paths src --ignore-src -r -y
```

### Development Tools
```bash
# Format Python code
black src/
autopep8 --in-place --aggressive --aggressive src/**/*.py

# Lint code
flake8 src/
pylint src/

# Type checking
mypy src/

# C++ formatting
clang-format -i src/**/*.cpp src/**/*.hpp
```

### ROS 2 Specific
```bash
# Source workspace
source install/setup.bash

# Launch simulation
ros2 launch robot_bringup gazebo.launch.py

# Run navigation stack
ros2 launch nav2_bringup navigation_launch.py

# Monitor topics
ros2 topic list
ros2 topic echo /cmd_vel

# Record bag files
ros2 bag record -a
```

### Hardware Testing
```bash
# Check hardware connections
lsusb
ls /dev/tty*

# Monitor system resources
htop
iotop

# Camera testing
v4l2-ctl --list-devices
```

## Project Structure
```
robotics_project/
├── src/
│   ├── robot_description/     # URDF, meshes, configs
│   ├── robot_bringup/        # Launch files
│   ├── robot_control/        # Controllers and drivers
│   ├── robot_navigation/     # Navigation stack
│   ├── robot_perception/     # Computer vision, sensors
│   └── robot_interfaces/     # Custom messages, services
├── config/                   # Configuration files
├── launch/                   # Launch files
├── maps/                     # Navigation maps
├── worlds/                   # Gazebo world files
└── scripts/                  # Utility scripts
```

## Dependencies
- ros-humble-desktop-full
- ros-humble-moveit
- ros-humble-navigation2
- ros-humble-gazebo-ros-pkgs
- python3-opencv
- python3-numpy
- python3-scipy
- python3-matplotlib

## Testing Strategy
- Unit tests with pytest (Python) and gtest (C++)
- Integration tests with launch_testing
- Simulation testing in Gazebo
- Hardware-in-the-loop testing
- Performance benchmarking

## Documentation
- Code documentation with Sphinx (Python) and Doxygen (C++)
- ROS 2 package documentation
- Hardware setup guides
- API reference documentation

## Debugging Tools
- **ROS 2 Tools**: rqt, ros2 doctor, ros2 wtf
- **Visualization**: RViz2, PlotJuggler
- **Profiling**: ros2_tracing, perf
- **Network**: Wireshark for DDS traffic
- **Hardware**: oscilloscope, multimeter for electronics

## Safety Considerations
- Emergency stop functionality
- Fail-safe behaviors
- Hardware limits and constraints
- Safety-certified components where required
- Testing procedures and validation

## Version Control
- Git with conventional commits
- Feature branches for development
- CI/CD with GitHub Actions or GitLab CI
- Automated testing and deployment

## Hardware Platforms
- **Single Board Computers**: Raspberry Pi, NVIDIA Jetson
- **Microcontrollers**: Arduino, ESP32, STM32
- **Sensors**: LiDAR, cameras, IMU, encoders
- **Actuators**: Servo motors, stepper motors, DC motors
- **Communication**: CAN bus, I2C, SPI, UART

忠実に公式の書き方に従った書き方になってます。
Development Workflowを定義するように指示するべきでした。

次。GPT-5の結果。
他の作業もさせていたためか日本語を挿入してくれています。

CLAUDE.md

# CLAUDE.md — Robotics Development (Open Source Focus)

バージョン: 2025-09-23  
Status: Draft / Living Document (随時更新)  
Language: Bilingual (EN + 日本語)  

---
## 1. Purpose / 目的
This document defines how we collaborate with Claude for open-source based robotics development (ROS 2, simulation, perception, control, tooling). It provides prompt patterns, conventions, safety & quality guardrails.  
このドキュメントは、ROS 2 などのオープンソースを活用したロボット開発において Claude を効果的かつ安全に利用するための指針・プロンプト・規約をまとめたものです。

---
## 2. Scope / スコープ
- Mobile robots / manipulators / embedded edge controllers
- ROS 2 (Humble / Iron), Gazebo (Ignition / Fortress), MoveIt 2, Nav2, micro-ROS
- Perception: OpenCV, PCL, Open3D, YOLO / RT-DETR (optional), depth cameras
- Control: trajectory planning, kinematics, dynamics (Pinocchio, Ruckig), realtime loops
- Tooling: colcon, CMake, Python, Docker, VSCode Dev Containers

Out of scope: proprietary closed toolchains unless explicitly noted.

---
## 3. Core Principles / 基本原則
1. Open Source First — Prefer permissive or compatible licenses (Apache 2.0, MIT, BSD).  
2. Reproducibility — Every generated procedure must be runnable via documented commands.  
3. Safety & Ethics — No unsafe actuation instructions without simulation validation.  
4. Incremental Complexity — Start minimal (sim → hardware).  
5. Determinism & Real-Time Awareness — Respect executor / callback group design.  
6. Traceability — Each AI-assisted change must reference a ticket / issue ID.

---
## 4. Repository Conventions / リポジトリ規約
```text
repo/
  docs/
    CLAUDE.md            # This file
    architecture/*.md
  ros2_ws/
    src/
      /
        package.xml
        CMakeLists.txt
        include//...
        src/...
        launch/...
        config/...
  simulation/
    worlds/
    models/
  scripts/
  docker/
  tests/
    integration/
    simulation/
```

Naming: ROS 2 packages use `snake_case`; C++ namespaces `snake_case`; Python modules lowercase.  
Branch naming: `feat/`, `fix/`, `exp/`, `docs/...`  
Commit tag examples: `[nav2]`, `[perception]`, `[sim]`, `[control]`.

---
## 5. Licensing & Attribution / ライセンスと表記
When Claude suggests code derived from known projects (e.g., ROS 2 examples), ensure:  
- Keep original copyright header if recognizable.  
- Record source URL in PR description.  
- Avoid GPL-incompatible mixing (unless repo is GPL).  
- For embedded firmware (e.g., micro-ROS + FreeRTOS), verify license compatibility matrix.

---
## 6. Claude Interaction Guidelines / Claude 利用ガイド
Always provide:  
- Context (package, node role, constraints)  
- Interfaces (topics/services/actions, QoS)  
- Performance or real-time limits (latency, cycle time)  
- Safety assumptions (e-stop availability, simulation vs hardware)  
- Output format (code block language, table, checklist)  

Avoid vague prompts like: "Optimize navigation." Prefer:  
"Optimize Nav2 path replanning frequency from 2 Hz to ≥10 Hz on Jetson Orin, CPU budget <40%, show profiling method and config deltas."  

---
## 7. Prompt Templates / プロンプトテンプレート
### 7.1 Code Generation (C++ Node)
EN:
```
You are assisting with a ROS 2 C++ rclcpp node for a differential drive robot.
Goal: Subscribe to /scan (sensor_msgs/msg/LaserScan) and publish /cmd_vel (geometry_msgs/msg/Twist) with simple obstacle avoidance.
Constraints:
- ROS 2 Humble
- Avoid dynamic memory in callback; preallocate.
- Keep loop period at 50 ms.
Provide: 1) package.xml snippet, 2) CMakeLists additions, 3) node implementation, 4) launch file, 5) test strategy.
Output: markdown sections with language-tagged code blocks.
```
日本語:
```
ROS 2 C++ ノードを作成してください。/scan を購読し /cmd_vel を出力する簡易障害物回避。
条件: Humble, コールバック内で動的確保禁止, 50ms 周期, テスト方針含む。
```

### 7.2 Diagnostics & Debugging
```
Context: Unexpected 150 ms latency in navigation stack (expected <60 ms). Hardware: Jetson Orin, CPU usage 35%.
Request: Identify potential ROS 2 Nav2 bottlenecks. Provide stepwise profiling plan (ros2_tracing, perf, ros2 topic hz), config parameters to inspect, and expected healthy ranges. Output as table + prioritized action list.
```

### 7.3 Simulation Scenario Creation
```
Task: Create a Gazebo (Fortress) world for a warehouse: 20 shelving units, 2 AMR robots.
Need: 1) world file stub, 2) spawning launch script (ROS 2), 3) model placement strategy, 4) validation checklist.
Constraints: Keep total poly count low (<150k). Provide resource paths.
```

### 7.4 Perception Pipeline Refinement
```
Goal: Improve 3D obstacle clustering using PCL from 12 Hz to ≥20 Hz.
Inputs: Organized point cloud 1280x720, range 0.3-8 m.
Platform: x86_64 desktop.
Ask: Suggest pipeline changes (voxel grid size, outlier removal, segmentation), each with estimated complexity + expected speed gain. Provide benchmark script skeleton.
```

### 7.5 Safety Review
```
Perform a safety review of the differential drive control stack.
Provide: Failure modes table (component, failure, effect, mitigation), required ROS 2 lifecycle states, and monitoring topics.
Assume single MCU for motor drivers, include watchdog strategy.
```

### 7.6 Hardware Bring-Up
```
Context: New LiDAR (RPLIDAR A3) integration.
Need: 1) udev rule pattern, 2) ROS 2 driver launch snippet, 3) verification commands, 4) troubleshooting decision tree.
```

### 7.7 Real-Time Tuning
```
Task: Reduce jitter in a 1 kHz control loop on PREEMPT_RT kernel.
Provide: Thread priority assignment, executor design, lock-free data passing strategy, measurement method.
```

---
## 8. Guardrails / ガードレール
| Area | Rule | Rationale |
|------|------|-----------|
| Hardware Commands | Never produce motion code without sim validation step | Prevent unsafe actuation |
| Licensing | Always note license of copied snippet | Compliance |
| Real-Time | Avoid unbounded allocations in loops | Determinism |
| Data Logging | Cap log rate; note storage impact | Prevent disk exhaustion |
| AI Output Trust | Require human review before merge | Quality & Safety |

Checklist before accepting AI-generated code:
- [ ] Builds with `colcon build --merge-install`
- [ ] Passes `ament_lint` / `clang-tidy` style rules
- [ ] QoS profiles explicitly set (no hidden defaults for critical topics)
- [ ] Launch file includes namespacing & remap clarity
- [ ] Unit/integration test stubs added

---
## 9. Testing Strategy / テスト戦略
Levels:
1. Static: `ament_lint`, `cppcheck`, `clang-tidy`, `ruff` (Python)  
2. Unit: GTest / PyTest for pure logic (topic marshalling mocked)  
3. Integration: Launch tests with simulated sensors  
4. Simulation: Gazebo scenario regression (nightly)  
5. Hardware-in-the-Loop (HIL): After simulation pass  
6. Performance: Latency + CPU sampling (perf, LTTng / ros2_tracing)  

Metrics to record (CSV + dashboard): callback latency, message drop %, CPU core distribution, memory usage, path planning time, cluster processing FPS.

---
## 10. Performance & Real-Time Notes / 性能・リアルタイム
- Use multi-threaded executor for high-frequency perception + planning separation.  
- Pin high-rate control threads to isolated cores (e.g., `cset shield`).  
- Preallocate vectors in perception loops; reuse buffers.  
- Prefer `loaned_message` where supported (Zero-copy).  
- Use `RCLCPP_INFO_THROTTLE` for rate-limited logging.  

---
## 11. Simulation Workflow / シミュレーション手順
1. Launch world: `ros2 launch sim_bringup warehouse.launch.py`  
2. Spawn robot(s) & sensors  
3. Run navigation stack with fake odom → verify TF tree  
4. Record `ros2 bag` dataset for reproducible test  
5. Evaluate KPIs (time to first plan, path smoothness, CPU)  
6. Only after thresholds met → proceed to hardware test plan.

---
## 12. Security & Privacy / セキュリティ
- Strip proprietary config before sharing prompts to Claude.  
- Do not paste hardware serial numbers or credentials.  
- Mask network topology details if sensitive.  

---
## 13. Failure Mode Template / FMEA テンプレート
```
| Component | Failure | Effect | Detection | Mitigation | Severity (1-5) | Occurrence (1-5) | Action |
```
Claude Prompt:
```
Generate FMEA rows for the manipulator joint controller (6 DOF) focusing on encoder faults, torque saturation, and comms timeout. Output table, highest RPN first.
```

---
## 14. Contribution Flow / コントリビュートフロー
1. Open issue with context + acceptance criteria  
2. Draft prompt to Claude attaching issue ID  
3. Generate code in feature branch  
4. Run local QA checklist  
5. Open PR referencing issue, include AI prompt + deltas summary  
6. Human review mandatory  
7. Merge & tag if release-worthy  

---
## 15. Example High-Quality Prompt / 良いプロンプト例
```
[Context]
Package: perception_pipeline (ROS 2 Humble)
Goal: Optimize point cloud downsampling before clustering.
Current: Voxel leaf size 0.02 m → 12 Hz overall.
Target: ≥20 Hz, minimal cluster deformation.
Constraints: CPU only, no GPU. Accept ≤5% increase in false splits.
[Request]
1. Suggest 3 alternative parameter sets (+ pros/cons)
2. Provide benchmark node code (C++)
3. Include rclcpp::Time based latency measurement
4. Output final summary table.
[Output Format]
Markdown with sections: Options, Benchmark Code, Launch, Metrics Table.
```

---
## 16. Quick Reference / クイックリファレンス
| Item | Command / Note |
|------|----------------|
| Build | `colcon build --symlink-install` |
| Test | `colcon test --event-handlers console_direct+` |
| Lint (C++) | `ament_cpplint` / `clang-tidy` via `ament_clang_tidy` |
| Lint (Python) | `ruff check .` |
| Run simulation | `ros2 launch sim_bringup warehouse.launch.py` |
| Topic graph | `ros2 topic list`, `rqt_graph` |
| Performance trace | `ros2 trace -s session_name` |

---
## 17. Change Log / 変更履歴
| Date | Author | Change |
|------|--------|--------|
| 2025-09-23 | AI (CLAUDE.md scaffold) | Initial version |

---
## 18. Future Enhancements / 今後の拡張案
- Add concrete package examples (navigation + manipulator)  
- Provide real trace screenshots  
- Add CI pipeline YAML template  
- Add firmware integration guidelines (micro-ROS)  

---
## 19. Disclaimer / 免責
AI-generated suggestions must be validated in simulation and code-reviewed before deployment to physical hardware. Actual hardware testing must follow lab safety procedures.

---
End of CLAUDE.md

基本的に書き方の形式は公式の通りです。
GPT-5はGPLを使うな、としてくれています。
読むのが大変なくらい出力してくれています。

最後。Grok Code Fast 1です。

CLAUDE.md

# CLAUDE.md - Robotics Development Assistant

You are Claude, an AI assistant specialized in robotics development using open source tools and frameworks. Your expertise covers:

## Core Competencies
- **Hardware Design**: CAD modeling, electronics schematics, PCB design
- **Software Development**: Embedded systems, ROS (Robot Operating System), Python/C++/Rust programming
- **Computer Vision**: OpenCV, TensorFlow/PyTorch for vision tasks
- **Motion Control**: Servo motors, stepper motors, PID controllers
- **Sensor Integration**: IMU, LiDAR, cameras, ultrasonic sensors
- **Simulation**: Gazebo, Webots, PyBullet for testing and validation

## Open Source Tools & Libraries
- **ROS/ROS2**: Primary framework for robot software development
- **Arduino/Raspberry Pi**: Microcontroller and SBC platforms
- **OpenSCAD/FreeCAD**: 3D modeling and CAD
- **KiCad**: PCB design and schematic capture
- **OpenCV**: Computer vision library
- **PCL (Point Cloud Library)**: 3D point cloud processing
- **MoveIt**: Motion planning framework
- **Gazebo**: Robot simulation environment

## Development Workflow
1. **Requirements Analysis**: Understand robot specifications and use case
2. **System Design**: Architecture planning, component selection
3. **Prototyping**: Hardware assembly, basic software integration
4. **Development**: Iterative coding, testing, debugging
5. **Testing & Validation**: Unit tests, integration tests, real-world validation
6. **Documentation**: Code comments, README files, technical documentation

## Best Practices
- Use version control (Git) for all projects
- Write modular, reusable code
- Implement proper error handling and logging
- Document hardware connections and pinouts
- Test in simulation before deploying to hardware
- Follow ROS conventions and package structure
- Use open source licenses (MIT, Apache 2.0, GPL)

## Example Tasks
- Design a wheeled robot chassis using FreeCAD
- Implement autonomous navigation using ROS navigation stack
- Create a computer vision pipeline for object detection
- Develop a robotic arm control system with inverse kinematics
- Build a sensor fusion system combining IMU and LiDAR data

When assisting with robotics projects:
- Always prioritize safety and reliability
- Recommend open source alternatives to proprietary solutions
- Provide code examples with proper comments
- Suggest testing procedures and validation methods
- Encourage learning and experimentation

Remember: Robotics development requires careful consideration of hardware limitations, real-time constraints, and safety protocols. Always test thoroughly and iterate based on results.

書き方の形式は公式の通りです。
ただGPLだったりFreeCADなどを使おうとしているので、会社の中での開発という情報を与えた方が良かったと思います。
会社の中での開発という情報を与えたらSOLIDWORKSを使おうとするのかな ?
Core Competenciesを最初に持ってくるのは非常に好感が持てます。

置き場所について。

自分の全ての開発に共通するような内容 : ~/.claude/CLAUDE.md
git repository直下 : ~/git/dev_XXX/CLAUDE.md

1-2. Tune your CLAUDE.md files

CLAUDE.mdを向上させ続けるべきです。

公式の内容がおそらく汎用的にするために抽象的なので、具体的な例をClaude Opus 4.1に提示してもらいます。

指示内容 : clude codeでsharp keysを使って、CLAUDE.mdをrefineするという具体的な場面を説明してください。説明内容を新規ファイルとして保存してください。

英語で指示 : Please explain how to use sharp keys in the claude code to refine CLAUDE.md. Save the explanation as a new file.

sharp_keys_explanation.md

# Using Sharp Keys in Claude Code to Refine CLAUDE.md

## Overview
Sharp keys (`#`) in Claude Code serve as a quick memory annotation mechanism that allows you to add contextual information and memories to enhance your project's configuration and Claude's understanding of your codebase.

## What are Sharp Keys?
Sharp keys are shortcuts using the `#` symbol that provide a fast way to:
- Add memories to your project context
- Create quick annotations for Claude to reference
- Enhance the CLAUDE.md configuration with contextual information

## How Sharp Keys Work with CLAUDE.md
The CLAUDE.md file serves as your project's configuration and instruction file for Claude Code. Sharp keys complement this by allowing you to:

1. **Quick Memory Addition**: Use `#` to rapidly add project-specific memories
2. **Contextual Annotations**: Create quick references that Claude can use during development
3. **Dynamic Configuration**: Add temporary or session-specific information without modifying the main CLAUDE.md

## Usage Patterns

### Basic Sharp Key Usage
```
# memory: Project uses ROS 2 Humble with custom navigation stack
# context: Main robot controller is in src/robot_control/
# note: Hardware testing requires physical robot connection
```

### Refining CLAUDE.md with Sharp Keys
Sharp keys can be used to:
- Add temporary project insights
- Note recent changes or discoveries
- Provide session-specific context
- Create quick reminders for ongoing work

## Best Practices

### Memory Management
- Use sharp keys for temporary or evolving information
- Keep permanent project information in CLAUDE.md
- Use descriptive memory tags for better organization

### Integration with CLAUDE.md
- Sharp keys supplement, don't replace, CLAUDE.md content
- Use them for dynamic information that changes frequently
- Consider promoting useful sharp key memories to CLAUDE.md

### Typical Use Cases
1. **Development Sessions**: Quick notes about current work
2. **Bug Tracking**: Temporary annotations about issues
3. **Feature Development**: Context about ongoing implementations
4. **Testing Notes**: Quick observations during testing

## Example Workflow

1. **Start Development Session**
   ```
   # working on: Navigation stack optimization
   # current issue: Path planning algorithm needs tuning
   ```

2. **During Development**
   ```
   # discovered: Performance bottleneck in /src/robot_navigation/planner.cpp:142
   # solution: Need to implement A* algorithm caching
   ```

3. **End of Session**
   - Promote important discoveries to CLAUDE.md
   - Keep session-specific notes as memories
   - Clear temporary context if no longer relevant

## Advanced Usage

### Structured Memory Tags
```
# bug: Memory leak in sensor driver
# fix: Applied patch in commit abc123
# test: Verified fix with 24-hour stress test
# status: Ready for production
```

### Project Evolution Tracking
```
# milestone: Navigation stack v2.0 complete
# next: Implementing computer vision pipeline
# dependency: Waiting for new camera hardware
```

## Integration Benefits

Sharp keys enhance your CLAUDE.md configuration by:
- Providing real-time context updates
- Maintaining project history and evolution
- Creating a living memory system
- Enabling more precise assistance from Claude

## Conclusion

Sharp keys provide a powerful complement to CLAUDE.md for maintaining dynamic project context. Use them strategically to enhance Claude's understanding of your robotics project while keeping your main configuration file focused on stable, long-term project information.

htmlを現在無料中のGrokに出力してもらいます。

sharp_keys_explanation.html

Using Sharp Keys in Claude Code to Refine CLAUDE.md

Overview

Sharp keys (#) in Claude Code serve as a quick memory annotation mechanism that allows you to add contextual information and memories to enhance your project’s configuration and Claude’s understanding of your codebase.

What are Sharp Keys?

Sharp keys are shortcuts using the # symbol that provide a fast way to:

  • Add memories to your project context
  • Create quick annotations for Claude to reference
  • Enhance the CLAUDE.md configuration with contextual information

How Sharp Keys Work with CLAUDE.md

The CLAUDE.md file serves as your project’s configuration and instruction file for Claude Code. Sharp keys complement this by allowing you to:

  1. Quick Memory Addition: Use # to rapidly add project-specific memories
  2. Contextual Annotations: Create quick references that Claude can use during development
  3. Dynamic Configuration: Add temporary or session-specific information without modifying the main CLAUDE.md

Usage Patterns

Basic Sharp Key Usage

# memory: Project uses ROS 2 Humble with custom navigation stack
# context: Main robot controller is in src/robot_control/
# note: Hardware testing requires physical robot connection

Refining CLAUDE.md with Sharp Keys

Sharp keys can be used to:

  • Add temporary project insights
  • Note recent changes or discoveries
  • Provide session-specific context
  • Create quick reminders for ongoing work

Best Practices

Memory Management

  • Use sharp keys for temporary or evolving information
  • Keep permanent project information in CLAUDE.md
  • Use descriptive memory tags for better organization

Integration with CLAUDE.md

  • Sharp keys supplement, don’t replace, CLAUDE.md content
  • Use them for dynamic information that changes frequently
  • Consider promoting useful sharp key memories to CLAUDE.md

Typical Use Cases

  1. Development Sessions: Quick notes about current work
  2. Bug Tracking: Temporary annotations about issues
  3. Feature Development: Context about ongoing implementations
  4. Testing Notes: Quick observations during testing

Example Workflow

  1. Start Development Session 
    # working on: Navigation stack optimization
# current issue: Path planning algorithm needs tuning
  2. During Development 
    # discovered: Performance bottleneck in /src/robot_navigation/planner.cpp:142
# solution: Need to implement A* algorithm caching
  3. End of Session
    • Promote important discoveries to CLAUDE.md
    • Keep session-specific notes as memories
    • Clear temporary context if no longer relevant

Advanced Usage

Structured Memory Tags

# bug: Memory leak in sensor driver
# fix: Applied patch in commit abc123
# test: Verified fix with 24-hour stress test
# status: Ready for production

Project Evolution Tracking

# milestone: Navigation stack v2.0 complete
# next: Implementing computer vision pipeline
# dependency: Waiting for new camera hardware

Integration Benefits

Sharp keys enhance your CLAUDE.md configuration by:

  • Providing real-time context updates
  • Maintaining project history and evolution
  • Creating a living memory system
  • Enabling more precise assistance from Claude

Conclusion

Sharp keys provide a powerful complement to CLAUDE.md for maintaining dynamic project context. Use them strategically to enhance Claude’s understanding of your robotics project while keeping your main configuration file focused on stable, long-term project information.

次。GPT-5です。

Claude_Refinement_Sharp_Keys_Quick_Guide.md

# Refining Claude.md with Sharp Keys – Quick Practical Guide
Version: 2025-09-26  
Status: Quick Operational Guide  
Language: EN + 日本語  

---
## 1. Goal / 目的
Give you a fast, repeatable method to improve sections of `Claude.md` using hash-tagged semantic blocks ("sharp keys") so revisions are scoped, reviewable, and automatable.  
`Claude.md` の特定セクションを安全かつ正確に改善するためのタグ付きプロンプト手順を示します。

---
## 2. Core Idea / コアアイデア
Use stable `#TAG` labels in your refinement prompt to:  
- Declare scope (`#SCOPE`) – which section(s) only  
- Embed original text (`#SOURCE_EXCERPT`) – prevent hallucination  
- Audit problems (`#AUDIT`) – explicit gap list  
- Define desired change (`#DELTA_GOAL`)  
- Constrain rewrite (`#REWRITE_RULES`) – word count / tables / style  
- Set acceptance gates (`#ACCEPTANCE`) – objective pass criteria  
- Trigger generation (`#REGEN_REQUEST`)  
- Plan next steps (`#FOLLOW_UP`)  

---
## 3. Minimal Template / 最小テンプレ
```
#SCOPE


#SOURCE_EXCERPT


#AUDIT
- Bullet list of issues / gaps

#DELTA_GOAL
Concise description of what the improved version must add / fix.

#REWRITE_RULES
- Style: imperative, concise
- Keep original key bullets (merge + enhance)
- Provide 1 table + ≤150 words prose
- Add explicit KPIs (latency, jitter)

#ACCEPTANCE
- Table with columns: KPI | Target | Tool | Threshold
- Original safety points retained
- Adds escalation path sentence

#REGEN_REQUEST
Generate the revised section now.

#FOLLOW_UP
(List deferred improvements for next round)
```

---
## 4. Example (Performance Section)
Prompt excerpt:
```
#SCOPE
Performance & Real-Time section only

#SOURCE_EXCERPT
( paste current bullet list )

#AUDIT
- No quantitative KPIs
- Missing measurement workflow ordering
- No alert thresholds

#DELTA_GOAL
Add KPI table + ordered measurement workflow + tuning levers categories.

#REWRITE_RULES
- ≤160 words prose
- 1 markdown table (KPI | Target | Tool | Alert | Notes)
- Add tuning levers: Executor, Scheduling, Memory
- Mention PREEMPT_RT vs generic kernel

#ACCEPTANCE
- Table present
- 3+ KPIs with numeric targets
- Original 5 practices preserved (may rephrase)
- Adds at least 2 measurement tools (ros2_tracing, perf)

#REGEN_REQUEST
Generate improved section.
```

---
## 5. Generated (Hypothetical) Output Pattern
```
## Performance & Real-Time
KPI Table ...
Workflow (ordered)...
Tuning Levers (grouped)...
Escalation rule...
```
If something missing (e.g., escalation path), add a follow-up prompt:  
```
Only append an 'Escalation' subsection referencing KPI alert thresholds.
```

---
## 6. Automation Hooks / 自動化
| Stage | Check | Tooling Idea |
|-------|-------|--------------|
| Pre-submit | Tags exist | Regex: ^#(SCOPE|SOURCE_EXCERPT|AUDIT|DELTA_GOAL|REWRITE_RULES|ACCEPTANCE|REGEN_REQUEST) |
| Lint | Word budgets | Count body tokens |
| Review | Acceptance met | Script parses table columns |
| Metrics | Churn per section | Parse #SCOPE IDs into CSV |

Git pre-commit sample rule: reject prompt if missing any required tag.

---
## 7. Japanese Quick Sheet / 日本語チートシート
```
#SCOPE: 対象セクション
#SOURCE_EXCERPT: 元テキスト原文
#AUDIT: 問題点列挙
#DELTA_GOAL: 改善ゴール
#REWRITE_RULES: 制約 (語数/表/保持要素)
#ACCEPTANCE: 受入条件
#REGEN_REQUEST: 実行指示
#FOLLOW_UP: 次回改善候補
```
ワークフロー: 抽出 → 監査 → ゴール → 制約 → 受入基準 → 生成 → レビュー → 変更ログ → 次回候補。

---
## 8. Acceptance Checklist Template
```
#ACCEPTANCE
- [ ] Original key points retained
- [ ] New KPI table added
- [ ] Numeric thresholds present
- [ ] Word budget satisfied (<160 words)
- [ ] At least 2 tools referenced
```

---
## 9. Anti-Patterns / アンチパターン
| Pitfall | Result | Fix |
|---------|--------|-----|
| Omitting #SOURCE_EXCERPT | Model invents content | Always paste original |
| Vague #DELTA_GOAL | Unusable rewrite | Make measurable (add KPI table) |
| No #ACCEPTANCE | Hard to approve | Define pass/fail upfront |
| Changing tag names | Breaks scripts | Keep stable taxonomy |
| Regenerate whole file | Merge drift | Narrow with #SCOPE |

---
## 10. Change Log Entry Format
When accepted:  
`2025-09-26: Refined Performance section (#PERF_KPI_PASS_01) – Added KPI table & workflow.`

---
## 11. Why This Scales
- Modular: Each refinement is a micro-spec.
- Auditable: Tags trace intent → output.
- Automatable: Lint + CI can gate quality.
- Low Risk: Scoped edits reduce regression probability.

---
## 12. Quick Start (TL;DR)
1. Copy target section → `#SOURCE_EXCERPT`
2. List gaps → `#AUDIT`
3. Define improvement → `#DELTA_GOAL`
4. Constrain format → `#REWRITE_RULES`
5. Set objective pass list → `#ACCEPTANCE`
6. Trigger → `#REGEN_REQUEST`
7. Review & merge + log

---
## 13. Summary / まとめ
Sharp key tagging converts a fuzzy "improve this" into a structured mini-spec that is testable, reviewable, and automatable—raising documentation and prompt engineering maturity.

---
End of Quick Guide

htmlをGPT-5 miniに出力してもらいます。

Claude_Refinement_Sharp_Keys_Quick_Guide.html

Refining Claude.md with Sharp Keys – Quick Practical Guide

Version: 2025-09-26
Status: Quick Operational Guide
Language: EN + 日本語

1. Goal / 目的

Give you a fast, repeatable method to improve sections of Claude.md using hash-tagged semantic blocks ("sharp keys") so revisions are scoped, reviewable, and automatable.
Claude.md の特定セクションを安全かつ正確に改善するためのタグ付きプロンプト手順を示します。

2. Core Idea / コアアイデア

Use stable #TAG labels in your refinement prompt to:

  • Declare scope (#SCOPE) – which section(s) only
  • Embed original text (#SOURCE_EXCERPT) – prevent hallucination
  • Audit problems (#AUDIT) – explicit gap list
  • Define desired change (#DELTA_GOAL)
  • Constrain rewrite (#REWRITE_RULES) – word count / tables / style
  • Set acceptance gates (#ACCEPTANCE) – objective pass criteria
  • Trigger generation (#REGEN_REQUEST)
  • Plan next steps (#FOLLOW_UP)

3. Minimal Template / 最小テンプレ

#SCOPE
<Which section(s) of Claude.md to refine>

#SOURCE_EXCERPT
<Exact copied text of current section>

#AUDIT
- Bullet list of issues / gaps

#DELTA_GOAL
Concise description of what the improved version must add / fix.

#REWRITE_RULES
- Style: imperative, concise
- Keep original key bullets (merge + enhance)
- Provide 1 table + ≤150 words prose
- Add explicit KPIs (latency, jitter)

#ACCEPTANCE
- Table with columns: KPI | Target | Tool | Threshold
- Original safety points retained
- Adds escalation path sentence

#REGEN_REQUEST
Generate the revised section now.

#FOLLOW_UP
(List deferred improvements for next round)

4. Example (Performance Section)

Prompt excerpt:

#SCOPE
Performance & Real-Time section only

#SOURCE_EXCERPT
( paste current bullet list )

#AUDIT
- No quantitative KPIs
- Missing measurement workflow ordering
- No alert thresholds

#DELTA_GOAL
Add KPI table + ordered measurement workflow + tuning levers categories.

#REWRITE_RULES
- ≤160 words prose
- 1 markdown table (KPI | Target | Tool | Alert | Notes)
- Add tuning levers: Executor, Scheduling, Memory
- Mention PREEMPT_RT vs generic kernel

#ACCEPTANCE
- Table present
- 3+ KPIs with numeric targets
- Original 5 practices preserved (may rephrase)
- Adds at least 2 measurement tools (ros2_tracing, perf)

#REGEN_REQUEST
Generate improved section.

5. Generated (Hypothetical) Output Pattern

## Performance & Real-Time
KPI Table ...
Workflow (ordered)...
Tuning Levers (grouped)...
Escalation rule...

If something missing (e.g., escalation path), add a follow-up prompt:

Only append an 'Escalation' subsection referencing KPI alert thresholds.

6. Automation Hooks / 自動化

Stage Check Tooling Idea
Pre-submit Tags exist Regex: ^#(SCOPE|SOURCE_EXCERPT|AUDIT|DELTA_GOAL|REWRITE_RULES|ACCEPTANCE|REGEN_REQUEST)
Lint Word budgets Count body tokens
Review Acceptance met Script parses table columns
Metrics Churn per section Parse #SCOPE IDs into CSV

Git pre-commit sample rule: reject prompt if missing any required tag.

7. Japanese Quick Sheet / 日本語チートシート

#SCOPE: 対象セクション
#SOURCE_EXCERPT: 元テキスト原文
#AUDIT: 問題点列挙
#DELTA_GOAL: 改善ゴール
#REWRITE_RULES: 制約 (語数/表/保持要素)
#ACCEPTANCE: 受入条件
#REGEN_REQUEST: 実行指示
#FOLLOW_UP: 次回改善候補

ワークフロー: 抽出 → 監査 → ゴール → 制約 → 受入基準 → 生成 → レビュー → 変更ログ → 次回候補。

8. Acceptance Checklist Template

#ACCEPTANCE
- [ ] Original key points retained
- [ ] New KPI table added
- [ ] Numeric thresholds present
- [ ] Word budget satisfied (<160 words)
- [ ] At least 2 tools referenced

9. Anti-Patterns / アンチパターン

Pitfall Result Fix
Omitting #SOURCE_EXCERPT Model invents content Always paste original
Vague #DELTA_GOAL Unusable rewrite Make measurable (add KPI table)
No #ACCEPTANCE Hard to approve Define pass/fail upfront
Changing tag names Breaks scripts Keep stable taxonomy
Regenerate whole file Merge drift Narrow with #SCOPE

10. Change Log Entry Format

When accepted:
2025-09-26: Refined Performance section (#PERF_KPI_PASS_01) – Added KPI table & workflow.

11. Why This Scales

  • Modular: Each refinement is a micro-spec.
  • Auditable: Tags trace intent → output.
  • Automatable: Lint + CI can gate quality.
  • Low Risk: Scoped edits reduce regression probability.

12. Quick Start (TL;DR)

  1. Copy target section → #SOURCE_EXCERPT
  2. List gaps → #AUDIT
  3. Define improvement → #DELTA_GOAL
  4. Constrain format → #REWRITE_RULES
  5. Set objective pass list → #ACCEPTANCE
  6. Trigger → #REGEN_REQUEST
  7. Review & merge + log

13. Summary / まとめ

Sharp key tagging converts a fuzzy "improve this" into a structured mini-spec that is testable, reviewable, and automatable—raising documentation and prompt engineering maturity.

End of Quick Guide

最後。Grok Code Fast 1です。

sharp_keys_refinement_explanation.md

# Using Sharp Keys to Refine CLAUDE.md

## Introduction
Sharp keys, represented by the hash symbol (#), are a fundamental feature in Markdown for creating structured headings. In the context of Claude code (documentation and instructions for AI assistants like Claude), using sharp keys effectively can transform a plain text document like CLAUDE.md into a well-organized, hierarchical structure that enhances readability, navigation, and maintainability.

## What Are Sharp Keys?
Sharp keys are the # symbols used at the beginning of lines to denote headings in Markdown:
- `#` creates a level 1 heading (largest, most prominent)
- `##` creates a level 2 heading
- `###` creates a level 3 heading
- And so on, up to level 6 (`######`)

These headings automatically create a table of contents in many Markdown viewers and provide semantic structure to the document.

## How to Use Sharp Keys to Refine CLAUDE.md

### Step 1: Analyze the Current Structure
Before adding sharp keys, review the existing CLAUDE.md content. Identify natural sections, subsections, and key points that can be grouped under headings. For example, in a robotics development guide, you might have sections for competencies, tools, workflow, etc.

### Step 2: Add Top-Level Headings
Start with level 1 headings (`#`) for major sections. These should represent the primary divisions of your document. For instance:
```
# Core Competencies
```
Becomes:
```
# Core Competencies
```

### Step 3: Create Subsections with Level 2 Headings
Use level 2 headings (`##`) for subsections within each major section. This creates a hierarchical structure:
```
## Hardware Design
## Software Development
## Computer Vision
```

### Step 4: Add Further Levels as Needed
For more detailed breakdowns, use level 3 (`###`) or deeper headings:
```
### Sensors and Actuators
#### Implementation Tips
```

### Step 5: Format Lists and Content
Ensure that content under headings is properly formatted. Use bullet points (`-`) or numbered lists for items within sections. Bold (`**text**`) or italic (`*text*`) important terms.

### Step 6: Validate and Refine
After adding headings, preview the document to ensure the hierarchy makes sense. Adjust heading levels if some sections need to be promoted or demoted for better flow.

## Benefits of Using Sharp Keys in CLAUDE.md
- **Improved Readability**: Headings break up text and guide the reader through the content.
- **Better Organization**: Logical structure makes it easier to locate specific information.
- **Enhanced Navigation**: Many platforms automatically generate tables of contents from headings.
- **Professional Appearance**: Well-structured documents appear more authoritative and polished.
- **SEO and Accessibility**: Proper heading structure improves search engine indexing and screen reader compatibility.

## Example Refinement
Here's how a section of CLAUDE.md might be refined:

**Before:**
```
You are Claude, an AI assistant specialized in robotics development using open source tools and frameworks. Your expertise covers:
Hardware Design: CAD modeling, electronics schematics, PCB design
Software Development: Embedded systems, ROS (Robot Operating System), Python/C++/Rust programming
```

**After:**
```
# Claude.md - Robotics Development Assistant

You are Claude, an AI assistant specialized in robotics development using open source tools and frameworks. Your expertise covers:

## Core Competencies
- **Hardware Design**: CAD modeling, electronics schematics, PCB design
- **Software Development**: Embedded systems, ROS (Robot Operating System), Python/C++/Rust programming
```

## Conclusion
By systematically applying sharp keys to create a hierarchical heading structure, you can significantly refine CLAUDE.md, making it more effective as a guide for AI assistants and human readers alike. This approach not only improves the document's usability but also demonstrates best practices in technical documentation.

htmlです。

Using Sharp Keys to Refine CLAUDE.md

Introduction

Sharp keys, represented by the hash symbol (#), are a fundamental feature in Markdown for creating structured headings. In the context of Claude code (documentation and instructions for AI assistants like Claude), using sharp keys effectively can transform a plain text document like CLAUDE.md into a well-organized, hierarchical structure that enhances readability, navigation, and maintainability.

What Are Sharp Keys?

Sharp keys are the # symbols used at the beginning of lines to denote headings in Markdown:

  • # creates a level 1 heading (largest, most prominent)
  • ## creates a level 2 heading
  • ### creates a level 3 heading
  • And so on, up to level 6 (######)

These headings automatically create a table of contents in many Markdown viewers and provide semantic structure to the document.

How to Use Sharp Keys to Refine CLAUDE.md

Step 1: Analyze the Current Structure

Before adding sharp keys, review the existing CLAUDE.md content. Identify natural sections, subsections, and key points that can be grouped under headings. For example, in a robotics development guide, you might have sections for competencies, tools, workflow, etc.

Step 2: Add Top-Level Headings

Start with level 1 headings (#) for major sections. These should represent the primary divisions of your document. For instance:

# Core Competencies

Becomes:

# Core Competencies

Step 3: Create Subsections with Level 2 Headings

Use level 2 headings (##) for subsections within each major section. This creates a hierarchical structure:

## Hardware Design
## Software Development
## Computer Vision

Step 4: Add Further Levels as Needed

For more detailed breakdowns, use level 3 (###) or deeper headings:

### Sensors and Actuators
#### Implementation Tips

Step 5: Format Lists and Content

Ensure that content under headings is properly formatted. Use bullet points (-) or numbered lists for items within sections. Bold (**text**) or italic (*text*) important terms.

Step 6: Validate and Refine

After adding headings, preview the document to ensure the hierarchy makes sense. Adjust heading levels if some sections need to be promoted or demoted for better flow.

Benefits of Using Sharp Keys in CLAUDE.md

  • Improved Readability: Headings break up text and guide the reader through the content.
  • Better Organization: Logical structure makes it easier to locate specific information.
  • Enhanced Navigation: Many platforms automatically generate tables of contents from headings.
  • Professional Appearance: Well-structured documents appear more authoritative and polished.
  • SEO and Accessibility: Proper heading structure improves search engine indexing and screen reader compatibility.

Example Refinement

Here's how a section of CLAUDE.md might be refined:

Before:

You are Claude, an AI assistant specialized in robotics development using open source tools and frameworks. Your expertise covers:
Hardware Design: CAD modeling, electronics schematics, PCB design
Software Development: Embedded systems, ROS (Robot Operating System), Python/C++/Rust programming

After:

# Claude.md - Robotics Development Assistant

You are Claude, an AI assistant specialized in robotics development using open source tools and frameworks. Your expertise covers:

## Core Competencies
- **Hardware Design**: CAD modeling, electronics schematics, PCB design
- **Software Development**: Embedded systems, ROS (Robot Operating System), Python/C++/Rust programming

Conclusion

By systematically applying sharp keys to create a hierarchical heading structure, you can significantly refine CLAUDE.md, making it more effective as a guide for AI assistants and human readers alike. This approach not only improves the document's usability but also demonstrates best practices in technical documentation.

1-3. Curate Claude's list of allowed tools

僕の解釈。

rm -rfなんかは駄目に決まっているけどgit commitとかは許可なしでいいという設定にすると効率が上がります。

bashに限らずMCPも同様。

bash commandsやMCP toolsについて広く知り、その安全性について判断ができると、安全かつ効率が良い状況を作れますよ。

1-4. If using GitHub, install the gh CLI

僕の解釈。

ClaudeはGitHub APIも使えるしGitHubの使い方も知ってるよ。

広告

IT開発関連書とビジネス書が豊富な翔泳社の通販『SEshop』
さくらのレンタルサーバ
ムームードメイン
Ｏｉｓｉｘ（おいしっくす）
らでぃっしゅぼーや
珈琲きゃろっと
エプソムソルト
AdGuard Ad Blocker
AdGuard VPN
AdGuard DNS



«       »