Introduction
Recently, I tried out Claude Code on a development project. I'm writing this down as a memo of what I learned and my thoughts on it.
What is Claude Code?
Claude Code is an AI agent developed by Anthropic, specialized for code generation. The official documentation describes it as follows:
Claude Code is an agentic coding tool that reads codebases, edits files, runs commands, and integrates with development tools. It's available in terminals, IDEs, desktop apps, and browsers. Claude Code is an AI-powered coding assistant that helps you build features, fix bugs, and automate development tasks. It can understand your entire codebase and work across multiple files and tools to complete tasks.
In short, it's a tool that autonomously handles the full development workflow: reading code, implementing changes, running tests, and creating pull requests on GitHub.
Background
In my day-to-day work, I maintain and develop various systems — one of which is an ETL tool. This ETL tool connects to various data sources to extract, transform, and load data. Development on it can broadly be divided into two workstreams:
- Developing the tool's interfaces and shared components
- Developing plugin-style modules that connect to individual data sources
The second workstream — plugin module development — involves a wide range of data sources such as MySQL, PostgreSQL, and Oracle, which demands significant time for development and research. As the customer base grows and development requests increase, the burden on engineers rises accordingly. Ideally, we'd be able to bring on additional engineers, but chronic understaffing has made that impossible.
On the other hand, plugin development follows fairly predictable patterns. So I thought: if I could standardize the development process as much as possible and automate it with Claude Code, I could reduce the workload — and that's what led me to adopt it.
Installation
Before getting started, you need to install the CLI:
npm install -g @anthropic-ai/claude-code
Once installed, run claude and complete API authentication. Just follow the terminal prompts and you should be fine.
Practices
CLAUDE.md
Starting with the official documentation, you can get up and running by following How Claude Code Works:
When you give Claude a task, it works through three phases: gathering context, taking actions, and verifying results. These phases blend together. Claude uses tools to search files to understand your code, edit them to make changes, and run tests to verify its work.
The agent autonomously handles research, development, and testing. To enable it to do this efficiently, engineers need to provide the necessary resources. This information goes into a markdown file called CLAUDE.md.
CLAUDE.md can be placed in several locations:
| Location | Description |
|---|---|
~/.claude/CLAUDE.md |
Applies to all Claude sessions |
./CLAUDE.md (project root) |
Check into git to share with your team |
./CLAUDE.local.md |
Add to .gitignore for local-only settings |
| Parent directories | Useful for monorepo setups |
| Child directories | Picked up on demand when Claude works in that directory |
For guidance on how to write a good CLAUDE.md, these articles are worth reading:
✅ What to include
- Bash commands Claude can't infer on its own
- Code style rules that differ from defaults
- Testing instructions and recommended test runners
- Repository etiquette (branch naming, PR conventions)
- Project-specific architectural decisions
- Development environment quirks (required environment variables)
- Common pitfalls or non-obvious behaviors
❌ What to exclude
- Anything Claude can understand by reading the code
- Standard language conventions Claude already knows
- Detailed API documentation (link to docs instead)
- Frequently changing information
- Long explanations or tutorials
- Per-file codebase explanations
- Self-evident practices like "write clean code"
💡 Best practice: Keep
CLAUDE.mdunder 500 lines. Since its contents are loaded into Claude Code's memory, shorter is better.
To get started, run /init to generate a sample template. Here's an example:
# Project Context
When working with this codebase, prioritize readability over cleverness.
Ask clarifying questions before making architectural changes.
## About This Project
FastAPI REST API for user authentication and profiles.
Uses SQLAlchemy for database operations and Pydantic for validation.
## Key Directories
- `app/models/` - database models
- `app/api/` - route handlers
- `app/core/` - configuration and utilities
## Standards
- Type hints required on all functions
- pytest for testing (fixtures in `tests/conftest.py`)
- PEP 8 with 100 character lines
## Common Commands
uvicorn app.main:app --reload # dev server
pytest tests/ -v # run tests
## Notes
All routes use `/api/v1` prefix. JWT tokens expire after 24 hours.
Skills
In addition to CLAUDE.md, preparing Skills files is another recommended practice.
Skills function like procedure manuals that guide the agent through specific tasks. By preparing a SKILL.md file, the agent will follow its steps during development.
Anthropic has published example skills in a public repository — a great reference for getting started:
For the ETL tool I described earlier, I prepared one skill per workstream. I can then give simple instructions like "create a new module" or "add a parameter to the interface", and the agent takes it from there.
The directory structure looks like this:
CLAUDE.md # Concise project overview & conventions
docs/skills/
new-plugin.md # Steps for creating a new plugin
add-interface-parameter.md # Steps for adding an interface parameter
Results
By automating development with the agent, tasks that would take a senior engineer about a week can now be completed in roughly an hour.
Additionally, using near-identical template-like prompts, virtually any engineer can now produce the same quality output — achieving faster delivery without sacrificing quality.
Closing Thoughts
That wraps up my introduction to Claude Code. What I've covered here is just the basics, and I'm sure there are many more ways to improve on this. I encourage you to try it out and share any useful patterns you discover!
As a side note — I often hear that AI will take engineers' jobs and previously had the same idea as well, but working with Claude Code has made me think the opposite. Using Claude Code effectively requires knowing good development processes, designing modules that are easy for AI to learn from, knowing how to write proper tests, and how to write clear markdown. Right now, software engineers are best positioned to do all of this. Rather than disappearing, I think the demand for engineers who can efficiently leverage AI will only grow.
What do you think? I'd love to hear your perspective.
Top comments (1)
The week → hour compression is real, but your framing of "how you give it instructions matters" is the key lesson that often gets buried under the raw speed numbers. Claude Code is a multiplier on prompt quality — if your initial context is vague, it will produce something vague quickly. If it's structured (clear objective, constraints, output expectations), it will produce something precise quickly.
That's the investment that makes the time savings stick. The 1-hour task this week can regress back toward a week if the prompt discipline slips, because you'll spend the time reviewing and correcting instead of building.
flompt (flompt.dev) was built for exactly this — a visual prompt builder that structures your instructions into 12 semantic blocks before they hit Claude Code or any other model. Same concept you discovered intuitively: structure first, speed follows.
Open-source: github.com/Nyrok/flompt