RSS Feed

Context Engineering: How I've Been Using Claude Code in My Development Workflow

Sat, 13 Sep 2025 09:31:28 GMT

Context engineering with AI assistants is evolving rapidly, and everyone seems to have their own approach. This article shares a workflow I’ve been experimenting with over a couple of months using Claude Code: a practical method for maintaining context across sessions, validating understanding, and turning AI collaboration into well-documented, testable code.

There are heaps of excellent resources on context engineering out there: Claude Code Best Practices from Anthropic, Simon Willison’s exploration of Claude Code, and Ethan Mollick’s deep dive into working with AI tools to name a few. Every day brings new articles with tips and tricks for using AI assistants effectively, it can be overwhelming, even repetitive at times. Some are genuinely insightful, others feel like variations on the same theme. What I want to share here is something different: my personal journey over the last few months. Not another prescriptive guide, but the workflow that’s actually stuck and made a tangible difference to how I write code.

I won’t give you prescriptive prompts or a CLAUDE.md file to copy and paste. Instead, I want to explain the workflow and reasoning behind it, so you can adapt it to your own context.

Building Context Through Dialogue

Working with large codebases presents a unique challenge: features rarely live in isolation. They span multiple files, interact with various systems, and carry implicit knowledge that’s often scattered across team members’ heads and outdated documentation.

What I found that worked great was starting with a simple premise: I already understand the code I’m working with, but I want to validate that understanding and create a shared context with Claude Code.

Here’s an example of how this works. I start by describing what I know about how a feature works in my own words. I’m not asking Claude to explain the code to me, I’m explaining it myself and asking for validation. I’ll typically mention an entry point where the logic begins, something like: “The search feature starts in search/handler.go and I believe it parses the query, builds the database filters, executes the search, and returns paginated results.”

Claude Code then gives me its understanding based on the actual code. This is where the magic happens: it’s not about getting an explanation, it’s about calibrating our shared understanding. If there’s a mismatch, I’ll follow up with corrections or clarifications until we’re aligned.

Once I’m happy with our shared understanding, I ask Claude Code to write this down in a markdown file; let’s call it SEARCH_FEATURE.md. Now I have a structured, written form of how this particular feature works. Remember, I’m documenting a specific feature, not the entire codebase. This focused approach keeps things manageable and relevant.

From Understanding to Planning

With our context documented, I start fresh with a /clear command. This clean slate is intentional: it forces me to be explicit about what context is needed for the next phase.

Now I can say: “Based on @SEARCH_FEATURE.md, I want to add pagination to our search results that currently return everything.”

But here’s where I add my own thinking to the mix. I’ll usually have ideas about implementation approaches, so I’ll include them: “We could use offset-based pagination which is simple, or cursor-based pagination which handles data changes better. Offset is easier to implement and gives page numbers, but cursor pagination performs better with large datasets. What’s the right choice here?”

I do this in plan mode (rotate shift + tab in Claude Code), which helps maintain focus on planning rather than jumping straight to implementation. The back-and-forth here is crucial, I challenge Claude Code with questions, explore edge cases, and refine until I’m confident we have not only a direction I’m happy with but also documented reasoning about alternatives considered.

Iterative Planning and Documentation

Claude Code tends to create plans with multiple phases, and I often tweak these. Sometimes it over-engineers things, so I’ll consolidate or remove phases. This granular control helps break down complex problems into manageable chunks, and I can git commit after each successful phase implementation.

Depending on the complexity, I’ll either append to the existing markdown file or create a new one for the plan. The key is maintaining that written record of decisions and approach.

Using Tests as Validation Checkpoints

Here’s a critical addition to my workflow that’s saved me countless hours: I ask Claude Code to write tests first, then use them as validation checkpoints. Instead of me manually checking if the implementation works, Claude runs the tests to verify correctness.

This TDD approach does consume more tokens due to iterative test-fail-implement-pass cycles and context accumulation. But here’s the thing: I’d write tests anyway, with or without AI. Tests are living documentation that verify the code works as intended. While code remains the source of truth, tests ensure that truth aligns with expectations. The token investment essentially automates what I’d do manually, with the added benefit of reduced debugging cycles and higher confidence in the implementation.

This creates a powerful feedback loop. The tests become the specification, and Claude Code iterates on the implementation until they pass.

Implementation with Precision

Time for another /clear, starting fresh for the implementation phase. This separation between planning and implementation has been crucial for keeping the context manageable.

My editor of choice is Neovim with the claudecode.nvim plugin, which has been particularly helpful for maintaining focus. Instead of saying “implement phase 2”, I can select specific lines from the plan and send them directly with references like @SEARCH_FEATURE.md#L7-17.

This approach has helped me explore code more effectively. When I need to understand a particular section, I can select it and ask targeted questions about its behaviour or edge cases. Being able to provide precise context has made these conversations much more productive.

Most of the time, I prefer to handle the git workflow myself, staging files as chunks of work are completed so I know exactly what’s being added. But I let Claude Code write the commit messages. It’s genuinely excellent at understanding what was done and writing comprehensive commit messages that capture both the what and the why.

This also helps with continuity. When I return to a feature hours later, instead of providing the entire plan again, I can just give Claude Code a couple of recent commits to read and it picks up right where we left off.

Conclusion

My development workflow is evolving, and I’m still figuring it out. The approach I’ve described here is what’s been working for me lately, but it’s constantly changing as I try to keep up with how quickly these tools are improving.

The biggest shift for me has been becoming more pragmatic. I still care deeply about clean APIs, good abstractions, and code that expresses clear intent, sometimes I find myself arguing with Claude about these things. But now that AI generates code for me, I’m learning to pick my battles. The craft still matters, but I’m less precious about being the one who types it all out.

Building context through documentation has become central to how I work, though I’m not committing these context files to git yet. These artifacts are still personal tools, they help me maintain continuity between sessions and occasionally help when explaining my thinking to teammates. But there’s a journey ahead in figuring out how this fits with how everyone else on the team works.

This way of working is still evolving. The tools keep changing, my approach keeps adapting, and I’m still discovering what works and what doesn’t. But for now, this structured context-building has shifted development from wrestling with complexity alone to having a conversation about solving problems, even if sometimes that conversation involves me shouting at Claude about proper error handling.

Retrospectives - Roles and Expectations

Sat, 11 Dec 2021 03:04:14 GMT

In the team that I work with, we run retrospective ceremonies every fortnight so that we can reflect on the work we’ve delivered by praising our doings and see how we can improve our work or processes. Recently I had the opportunity to run one of these meetings and this post is to share the format I’ve used and how things went in general.

Formats

I reckon that the most popular retrospective format is the triade “What worked, What we can keep doing and What didn’t work” or any variation of that (i.e. smile, sad and neutral faces, etc).

This format is great, but there are times where it can be quite challenging if we want to touch on certain topics. For example, if I want to assess how aligned we all are with regards to the role each one of us has to play in the Software Development, how can I discuss that if all I have is “What worked”, “What didn’t work”, etc?

In our team, there are a quite diverse number of roles, which is actually true in most of Software Development teams nowadays. We have people that are more focused on the product direction, people that are looking into how the user experience should be and Software Developers/Engineers like myself.

How the activity went out

The retrospective was divided into 2 steps:

Bullet point gathering from each participant and then, translated them into sticky notes trying to form a timeline from the Idea to Working Software.
Asked the participants to fill out the Roles and Expectations matrix

based on the bullet points above.

First step: bullet points from Idea to Software lifecycle

The first step was to gather bullet points from everyoneasking what are the steps to deliver a software, starting from the idea until the actual software in the hands of a customer.

I wanted to avoid any kind of bias, so I did this anonymously. Once I had all the data from everyone, I’ve added sticky notes to represent the different steps provided by everyone in some sort of timeline.

Here’s an example:

Second step: fill out the “Roles and Expectations” matrix

The second step was to discuss more in-depth roles and expectations. To do that, we created a matrix where the number of rows represents the many roles we wanted to discuss and two columns saying “I expect that…” and “I don’t expect that…”. This idea was born from a combination of Role Expectations Matrix and Is - Is not - Does - Does not exercises from FunRetrospectives website.

FunRetrospectives is an excellent source of different activities for running retros, so if you’re looking for different activities to run in your team, please check them out!

For this activity, I asked each member to add sticky notes with a short summary of what was the understanding of the expectation of each role, adding stickies for “I expect that…” and also adding stickies for “I don’t expect that…”. I also asked the participants to avoid the use of “+1” or any kind of emoji that would make others biased. The idea here was to have equal weight for every sticky note since we would have a separate moment for voting on the themes that we wanted to discuss and then, “+1“‘s would be appropriate.

No action items, for now…

It is usually expected that “Action Items” should be one of the outcomes from retrospectives and who owns these action items. For this retro though, I wanted to focus on the discussion instead of focusing on action items.

I’ve planned having 45 minutes just debating the “Roles and Expectations” sticky notes, appreciating how different views we might have in the team about the certain role and how we can agree on something together. With that, I tried to have 10 minutes time slot for the top voters, trying to cover as many roles as possible.

Takeaways from this particular retro

I’ve got feedback from the participants that the retro was quite insightful, which inspired me to write this post. On the occasion of this particular retro, as it might occur with many, there were some loose ends; we couldn’t figure everything out in one go. However, I believe we had an opportunity to speak freely about what things some believed that a Software Engineer should not do, for example, and appreciate that different people thought exactly opposite things.

Thank you for reading

I hope you enjoy this post, if you have any feedback or questions, hit me up on alabeduarte@gmail.com, I’d be happy to hear your thoughts and be better next time!

All the images were generated from excalidraw.com

Other References

The semantics of Marshalling in Go

Fri, 26 Mar 2021 10:38:35 GMT

In this post, I’d like to discuss how Marshalling/Unmarshalling process is usually applied in Go programs. I’ll give some examples of how it is used in practice with some code examples (i.e. data parsing) and then expand on other usages when we have the need for transforming data across different domains.

Before discussing the term Marshalling, I’d like to start with the word data in the context of programming languages. More often than not we programmers have a task that involves in some shape or form interacting with data represented in a format and then we need to transform this data into a different representation.

A few use-cases that come to mind:

Fetch data from this HTTP API and convert it into my own type to then do something…

As soon as this “data” arrives, transform them into something else, which is what our system understands…

In order to integrate with certain third-party API, I need to convert this “data” into something that the third-party API understands to then send the data…

What should we call this?

When it comes to changing data’s representation into another representation in Software, I would imagine some of these terms would ring a bell: Encode/Decode, Marshal/Unmarshal, Map, Normalise (also Normalize), Parse, Reduce, Serialise (also Serialize), Transform, etc.

You might notice that different programming languages use one more than another and, in Go, the terms Marshal and Unmarshal are usually preferred. In this post, I’d like to explore or try to guess why this is the case and what all of these terms have in common.

The term Marshalling

In the context of computer science and programming languages, the term marshalling is the process of transforming a data representation into a suitable format that will be used by a different Software Component.

This process is quite interesting because it enables interoperability between different Softwares. Consider Software X and Software Y, they are totally independent of one another. However, they can communicate with each other via message passing and they can exchange data, as long as they establish a common contract or interface.

i.e.

Software X –> Marshal data "abc" into "<abc>"
Software Y –> Unmarshal data "<abc>" into "A, B, C"

How Marshal/Unmarshal can be used in Go

In Go, one of the most famous examples you might find is converting data from a JSON structure into Go code (in other words, JSON “parsing”).

What about the term Parsing?

There is a quite popular term that can be seen as similar, but don’t assume that just yet, which is parsing. I would say that the semantics of parsing is more applicable when the data to be processed are strings/symbols that will then be transformed into a custom representation throughout the programming language in question.

While terms like Marshalling and Encoding offer a bit more scope to work with. Given you need to transform type A to type B while type A is a binary, I personally think that calling a “parser” doesn’t feel right.

Back to Marshalling and Unmarshalling

It took a bit longer but the term “Marshalling” clicked for me, eventually. When I first came to learn Go, call the method Unmarshal to “parse” JSON felt really weird and too much low-level.

However, Marshal/Unmarshal can and should be used as a generic way to transform types between boundaries regardless of the level of abstraction (i.e. network, application, domain, platform).

Converting from one format to another

When dealing with Distributed Systems, converting different representations from one domain to another can be quite common. And I’m not only referring to business domains (i.e. Shopping cart, Billing, Invoice) but also to different transport layers (i.e. Network, Protocols).

Data format transformations (i.e. JSON, XML, etc)

We can unmarshal from type A to type B when transporting data over the wire or when converting from a generic data representation to a domain-specific representation.

So let’s imagine we are building a system that manages user’s accounts and we have the following use-cases to cover:

Convert from XML
Convert from JSON
Convert from Protocol Buffers
etc.

Code examples

Unit tests (click to expand)

func Test_Unmarshal(t *testing.T) {
	tests := []struct {
		name string
		in   interface{}
		out  Account
	}{
		{
			name: "should unmarshal Account from XML",
			in: []byte(`
			<?xml version="1.0" encoding="UTF-8"?>
			<User>
				<Name>Mary</Name>
				<Type>Gold</Type>
			</User>
			`),
			out: Account{
				Name: "Mary",
			},
		},

		{
			name: "should unmarshal Account from JSON",
			in: []byte(`
			{
				"user": {
					"name": "John",
					"type": "Premium",
					"created_at": "2020-01-01"
				}
			}
			`),
			out: Account{
				Name: "John",
			},
		},

		{
			name: "should unmarshal Account from protobuf",
			in: ProtobufAccount{
				AccountName: "Bob",
			},
			out: Account{
				Name: "Bob",
			},
		},

		{
			name: "should not unmarshal from CSV format since it doesn't support yet",
			in:   []byte(`Name,Mary`),
			out:  Account{},
		},

		// ...
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			var a Account
			err := a.Unmarshal(tt.in)
			if err != nil {
				expectedError := fmt.Errorf("unable to unmarshal %v, format not supported.", tt.in)

				if err.Error() != expectedError.Error() {
					t.Errorf("unexpected error while trying to unmarshal account: %v", err)
				}
			}

			if tt.out != a {
				t.Errorf("test failed. wanted: %v, got: %v", tt.out, a)
			}
		})
	}
}

Implementation (click to expand)

// xmlPayload represents the XML payload with user data
type xmlPayload struct {
	Name string `xml:User>Name`
}

// jsonPayload represents the JSON payload wiht user data
type jsonPayload struct {
	User struct {
		Name string `json:"name"`
	} `json:"user"`
}

// ProtobufAccount represents a generated Go code from a protobuf definition
// More details: https://developers.google.com/protocol-buffers/docs/reference/go-generated
type ProtobufAccount struct {
	AccountName string `protobuf:"bytes,1,opt,name=acount_name,proto3"`
}

// Account is the domain representation of an account in the system. It is the
// main entity for the example we're using.
type Account struct {
	Name string
}

func (a *Account) unmarshalXML(src []byte) error {
	var res xmlPayload
	err := xml.Unmarshal(src, &res)
	a = &Account{
		Name: res.Name,
	}
	return err
}

func (a *Account) unmarshalJSON(src []byte) error {
	var res jsonPayload
	err := json.Unmarshal(src, &res)
	a = &Account{
		Name: res.User.Name,
	}
	return err
}

func (a *Account) unmarshalProtobuf(src ProtobufAccount) error {
	a = &Account{
		Name: src.AccountName,
	}

	return nil
}

// Unmarshal takes an interface{} and try to convert into Account type
func (a *Account) Unmarshal(src interface{}) error {
	switch src.(type) {
	case []byte:
		b := src.([]byte)

		// naive logic to determine if it is XML
		if strings.Contains(string(b), "<?xml") {
			return a.unmarshalXML(b)
		}

		// naive logic to determine if it is JSON
		if strings.Contains(string(b), `"user":`) {
			return a.unmarshalJSON(b)
		}
	case ProtobufAccount:
		return a.unmarshalProtobuf(src.(ProtobufAccount))
	}

	return fmt.Errorf("unable to unmarshal %v, format not supported.", src)
}

Converting from one domain to another

In this particular case, let’s imagine we have an e-commerce system that goes from adding item to a cart, placing an order and sending an invoice to the customer.

Once the customer selects an item and adds it to her/his cart, the item will be part of an order that will also be listed in the invoice afterwards. However, the “item” might not have the same meaning across the system.

I would suggest a read on Bounded Context for more details. It is described in more depth in the book Domain-Driven-Design

Without further ado, let’s check how Marshal and Unmarshal can be used to translate different data representations across different domains:

Because now the components are now communicating via a common interface (Marshal/Unmarshal), the data format that is used to transfer between components became merely an implementation detail. It no longer matters if an item, when unmarshalled to an Order, will be a JSON payload, protobuf or a just data transformation between go types. As the system supports different ways of data transformation (new domains being introduced, new formats, new integrations), the core flow doesn’t need to change, because now Marshal and Unmarshal abstracts that away.

Final thoughts

Although the Marshalling terminology might sound too low level (i.e. feels more about computation, less about business domain), it is a consistent way to transform data from one format to another, where this transformation can be from low-level bytes into an “object” or it can be used to translate from one domain representation to another.

One might argue that having a single interface to transform data between domains is nothing novel. However, having this semantics established is quite useful so developers won’t need to come up with new conventions all over again. Although I appreciate always having new ways to express real-life problems in form of code, I believe that data transformation, most of the time, are stepping stones for problem-solving, not the end goal. So if there is a standard way to deal with this mundane task, I found it very welcome.

But hey, this is only my opinion at the time of this post! If you read this far, I hope I didn’t waste your time!

Thank you for reading

I hope you enjoy this post, if you have any feedback or questions, hit me up on alabeduarte@gmail.com, I’d be happy to hear your thoughts and be better next time!

References

3 approaches to consider when rendering conditional content in React

Fri, 19 Feb 2021 07:54:24 GMT

In this post, I’d like to share alternative approaches for dealing with conditional rendering in React. I will try to list out the pros and cons about 3 different approaches (doesn’t mean couldn’t be more!) and hopefully this can be useful for you someday.

Use-case

Let’s consider we have a React component that is called AccountCard. The responsibility of this component is to display the user’s first name, last name and the avatar.

type AccountCardProps = {
  firstName: string;
  lastName: string;
  avatarURL: string;
}

const AccountCard: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
}) => (
  <div>
    <div>
      <img src={avatarURL} />
    </div>
    <div>
      <label>First name:</label>
      <span>{firstName}</span>

      <label>Last name:</label>
      <span>{lastName}</span>
    </div>
  </div>
)

// usage

// ...

<Account
  firstName="John"
  lastName="Doe"
  avatarURL="https:/example.com/slug-123.png"
/>

// ...

New requirements

Let’s imagine we’ve got a new requirement:

Premium Accounts should have a small badge indicating that the account is premium. As for regular accounts, the user card should stay the same.

Regular Account	Premium Account

Basically, we need to add a new badge only if the user’s account is premium, otherwise, we just render the component as it was before. It seems straightforward.

To make things more interesting and to justify why I’m writing this post, I’d like to consider the possibility where the current component <AccountCard /> could be in use by other teams and different places in the app.

With that said, in order to make the changes, we’ll need to make, we will need to consider our strategy carefully since we don’t want to break compatibility with other teams/areas where this component is already being used.

Approaches

I can imagine 3 approaches (probably there are more) and I’ll try to reason about the pros and cons of each one.

1. Adding a new prop with boolean values

Our goal is to display additional information on top of what is already there, so one way to approach this is to add a new prop to our component that indicate that the account is premium. In this case, we can simply use a boolean value to indicate whether the account is premium or not:

// Let's pretend we have a component that displays the "premium" badge
const PremiumBadge = () => <div>PREMIUM</div>

type AccountCardProps = {
  firstName: string;
  lastName: string;
  avatarURL: string;
  isPremium: boolean; // new prop
}

const Account: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
  isPremium, // new prop
}) => (
  <div>
    <div>
      <img src={avatarURL} />
    </div>
    <div>
      <label>First name:</label>
      <span>{firstName}</span>

      <label>Last name:</label>
      <span>{lastName}</span>
    </div>
    {/* if the value of isPremium is true, display the Premium badge */}
    {isPremium && <PremiumBadge />}
  </div>
)

// usage

// ...

<Account
  firstName="John"
  lastName="Doe"
  avatarURL="https:/example.com/slug-123.png"
  isPremium={true}
/>

// ...

Pros

Easy

It is an easy change that gets the job done. If there are no many people depending on this component and the impact of doing changes is low, I’d consider this approach in a heartbeat.

Cons

Our component will be subject to change every time we get a new requirement

The example I gave earlier of having to display a premium badge is simple because either we show a new content or not. However, software tends to evolve over time and I wouldn’t be surprised if we get to support new use cases in the future such as:

display this icon when the user is online.
display date of birth if a certain condition is met, etc.

Then, every time we get a new requirement will be a new prop and a new “if” tucked in in the component and every change needs to be well considered given there is now the risk of breaking the existing behaviour and impacting other teams.

It can break compatibility with existing code

If our component is being reused by other areas in the codebase, we will need to change everywhere to make sure the new prop is being passed correctly. We also would need to watch out for regression.

One way to mitigate the risk of breaking things or introducing breaking changes to other teams is to change the newly added prop to be set as optional and set its default value to be always false so that only the new usage of the code that needs the new prop isPremium will need to change passing false or true while places where this component is already in use don’t need to change a thing.

type AccountCardProps = {
  firstName: string;
  lastName: string;
  avatarURL: string;
  isPremium?: boolean; // new prop now marked as "optional"
}

const Account: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
  isPremium = false, // new prop
}) => (
// ...
);

2. Adding a new prop with an enum

As mentioned above, adding new props for every new use case will increase the the complexity of the component and it will require larger coordination between developers that already use it.

With that said, let’s try changing our data structure in a way that allows the users of our code to pass down what type of account will be displayed and we can write our component in a way that we will know what to do based on that.

// AccountType represents all possible types of account
enum AccountType {
  Regular,
  Trial,
  Premium,
  Gold,
}

// accountTypeComponentMap takes an AccountType as input and returns a React
// component based on the account type
const accountTypeComponentMap = (
  accountType: AccountType
): React.FunctionComponent => {
  const map = new Map([
    [AccountType.Regular, () => null], // for "regular" accounts, display nothing
    [AccountType.Trial, () => <div>TRIAL ACCOUNT</div>],
    [AccountType.Premium, () => <div>PREMIUM</div>],
    [AccountType.Gold, () => <div>GOLD</div>],
  ])

  // Fetch the component based on the account type
  // return nothing (null) if can't find it.
  return map[accountType] || null;
}

type AccountCardProps = {
  firstName: string;
  lastName: string;
  avatarURL: string;
  accountType: AccountType; // type that represents the account type (i.e.  premium, regular)
}

const Account: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
  accountType,
}) => {
  // Assign the corresponding component based on the account type
  const BadgeComponent = accountTypeComponentMap(accountType)

  return (
    <div>
      <div>
        <img src={avatarURL} />
      </div>
      <div>
        <label>First name:</label>
        <span>{firstName}</span>

        <label>Last name:</label>
        <span>{lastName}</span>
      </div>
      {/* displays the content */}
      <BadgeComponent />
    </div>
  )
}

// usage

// ...

<Account
  firstName="John"
  lastName="Doe"
  avatarURL="https:/example.com/slug-123.png"
  accountType={AccountType.Premium}
/>

// ...

Pros

Extensible

This solution opens the possibilities to be able to accommodate new use cases that are related to different types of accounts. As we have new types, all we have to do is to include in the list of supported types and add a a new entry in the map, then add the corresponding rendering logic to it:

i.e.

enum AccountType {
  // ...
  Diamond, // new type
}

// accountTypeComponentMap takes an AccountType as input and returns a React
// component based on the account type
const accountTypeComponentMap = (
  accountType: AccountType
): React.FunctionComponent => {
  const map = new Map([
    // ...
    [AccountType.Diamond, () => <div>...</div>],
  ])

  // Fetch the component based on the account type
  // return nothing (null) if can't find it.
  return map[accountType] || null;
}

Cons

It can also break compatibility with existing code

As we are adding a new prop, every consumer will need to update the code where this component is being used to accommodate the accountType. Perhaps now the situation can be trickier because other teams when updating the code, will also need to know what would be the default account type to be used since depending on what you pass in, it might render additional content.

To mitigate that, we would need to make sure the documentation is in place and perhaps have a pre-selected accountType if none is given. However, having this implicit might lead to confusion in the future so I’d choose this approach carefully.

i.e.

type AccountCardProps = {
  // ...
  accountType?: AccountType; // accountType now is optional
}

const Account: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
  accountType = AccountType.Regular, // account type will always be "regular"
}) => {
  // ...
});

3. Using composition

The implementation of this approach consists of having separate components that can be combined in order to achieve a broader “concept”.

The idea is to extend basic components into more specific ones as needed so that these components can be opted-in by developers as new features are introduced or tweaked. This principle is also called Open-closed principle. To illustrate this principle applied to our situation, our component is now closed for modification. Meaning that we don’t add new code, or at least we minimise the changes to it. However, we will now make it open for extension, meaning that whenever new requirements come, we extend our component into something new based on the original one as we would do with lego bricks.

Let’s see how our code would look like with this approach:

type AccountCardProps = {
  firstName: string;
  lastName: string;
  avatarURL: string;
}

const AccountCard: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
}) => (
  <React.Fragment>
    {/* replace <div> by <React.Fragment> */}
    <div>
      <img src={avatarURL} />
    </div>
    <div>
      <label>First name:</label>
      <span>{firstName}</span>

      <label>Last name:</label>
      <span>{lastName}</span>
    </div>
  </React.Fragment>
)

const PremiumAccountCard: React.FunctionComponent<AccountCardProps> = ({
  firstName,
  lastName,
  avatarURL,
}) => (
  <React.Fragment>
    <AccountCard
      firstName={firstName}
      lastName={lastName}
      avatarURL={avatarURL}
    />
    <div>PREMIUM</div>
  </React.Fragment>
)

// usage

// ...

<PremiumAccountCard
  firstName="John"
  lastName="Doe"
  avatarURL="https:/example.com/slug-123.png"
/>

// ...

Pros

Flexible

This approach is arguable the most flexible of all, but it can also be considered as over-engineering. All depends on the problem at hand.

Considering our use case, if the requirement is to just display a new badge when the user’s account is premium, breaking the component into a separate component might be too much. However, this approach can be really powerful because the original component doesn’t need to be changed necessarily, therefore, the codebase won’t be affected as we evolve our software.

Cons

Risk of introducing the wrong abstraction

Although I really like this approach, applying it too soon might hurt the code design since there is a risk of creating wrong abstractions for something we don’t fully understand yet. If that happens, might be hard to go back to the simplest state and there is a risk of the “composed” component become a hybrid beast (generic, but specific, which is pretty much unfortunate, no one wants that).

More about that:

Thank you for reading

If you read this far, I hope I didn’t waste your time.

I’ve talked about 3 approaches that I often consider in situations like this and I don’t believe there is a right or wrong approach to follow but I thought would be beneficial listing a few that came to mind here so it can be referenced later on as a head start in the case you – or future me – face similar challenges.

I hope you enjoy this post, if you have any feedback or questions, hit me up on alabeduarte@gmail.com, I’d be happy to hear your thoughts and be better next time!

Multiple .gitconfig files

Wed, 20 Jan 2021 07:16:30 GMT

What `.gitconfig` is for?

When you set up a new code and uses Git to manage your version control, unless you are only reading a code of a repository that you cloned, you will have to add some configuration to start interacting with Git, which is mainly to tell Git “who you are” since Git’s configurations are per-user.

For this post, let’s use the infamous John Doe as an example. I believe would be easier if we do some role play/story tell this because we will be discussing emails, directory names, company names and I’d like to avoid any situation where could lead you – the reader – to trouble (i.e. wrong filename, etc).

Say John Doe wants to set up Git and have more than one email (personal and work) and John Doe wants to make sure that the commits are being referenced properly so that other people might reach out to him directly in case of questions with changes and all. The challenge is that the company that John Doe works for requires every employee to use their work-email so John Doe needs to pay attention to his commits.

Getting started

For a complete guide on how to setup Git, I’d recommend the official guide, but to summarise, running the following commands will get you ready to go:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

The command above tells Git about your identity which is represented by your name and your email. This is important because every Git commit uses this information.

The --global flag means that these configurations will be stored in your system which will be placed in a file located at ~/.gitconfig.

NOTE: without the flag --global, the configuration provided will only be applied to the current directory.

Checking Your Settings

You can check your current Git settings by typing git config:

$ git config --list
user.name=John Doe
user.email=johndoe@example.com

You also can verify the ~/.gitconfig file:

$ cat ~/.gitconfig

[user]
  name = John Doe
  email = johndoe@example.com

Dealing with multiple configurations

Git’s API is big so I might not cover all options here, meaning there might be other ways to achieve the same thing wich is: be able to commit code using appropriate identifications without the hassle of manually change/check them.

The approach I’d like to share is to use includeIf. What includeIf does is to append a new peace of config from a different path conditionally so that way, if the conditions are met, an addition to the existing Git config will be considered when interacting with Git. This is based on which directory you’re on so in order to make the most use of includeIf it is recommended to keep all repositories within a single folder. For example:

- my-workspace/
  - xyz/
    - repository-1/
    - repository-2/
    (...)

Considering John Doe works at the company xyz and his email is j.doe@xyz.com, let’s create a new file containing the additional info that should only be used for work-related repositories:

1. Create a new file:

$ touch ~/my-workspace/xyz/.gitconfig-work

2. Add the work-related info to the newly created file:

[user]
  name = John Doe
  email = j.doe@xyz.com

3. Add conditional config to the global Git config

Now we need to tell Git that, if John Doe is within the work-specific directory (~/my-workspace/xyz/ on this case), Git should use a different configuration instead.

To make that happen, let’s change the system Git config file located on ~/.gitconfig and edit it with the following code:

[user]
  name = John Doe
  email = johndoe@example.com
[includeIf "gitdir:~/my-workspace/xyz/"]
  path = ~/my-workspace/xyz/.gitconfig-work

Dealing with different signature keys

Git is cryptographically secure and John Doe does not mess around, he wants to make sure that every commit is from a trusted source. Git provides a mechanism where you can sign your commits but now that John Doe has different Git configurations, we need to find a way to also setup different signatures depending on the identification (i.e. one signature for his personal email, another signature for his work’s email).

If you’re curious to know how to set up a GPG key with git, please read the official Git Tools documentation. Additionally, I’d recommend the following this tutorial published by GitHub.

Similarly to the steps, we followed to set up different configs based on the directory, let’s start:

1. Create a new file with “personal” config:

$ touch ~/my-workspace/side-projects/.gitconfig-personal

2. Add the signature (i.e. in our case, the signature is SECRET) to the newly created file:

[user]
  signingkey = SECRET

3. Add your work-related signature (i.e. SECRETWORK on this case) to your the work-related Git config

[user]
  name = John Doe
  email = j.doe@xyz.com
  signingkey = SECRETWORK

4. Now let’s configure our global `~/.gitconfig` with the following:

[includeIf "gitdir:~/my-workspace/xyz/"]
  path = ~/my-workspace/.gitconfig-work"
[includeIf "gitdir:~/my-workspace/side-projects/"]
  path = ~/my-workspace/side-projects/.gitconfig-personal

5. All set!

Now, John Doe can commit freely between personal/work-related with ease!

Thank you for reading

I hope you enjoy this post, if you have any feedback or questions, hit me up on alabeduarte@gmail.com, I’d be happy to hear your thoughts and be better next time!

Setting up a new machine

Fri, 08 Jan 2021 03:58:16 GMT

Dang! Got a new laptop and I have to set up everything… again…

I always find it exciting when I get something new, such as a new laptop. When buying one, changing jobs (assuming the employer provides me one) or replacing old by new.

The first thing I like to do is to assess the machine’s power, see what is made in terms of memory and disk space. Then, I see how far I can get in terms of privileges (i.e. can I install/uninstall whatever I want?).

This is important to me because I like to keep things clean and tidy so, eventually, I can start making my own mess by installing my stuff. During my career I kind of got a mental list of software I lean on, things that I really need, other things that I might need and others that I heard that are nice but I never really used it.

As I became to customise my settings more and more, having a new machine wasn’t that exciting anymore. I not only have to remember to install all of these things that I need, but it became also tedious and demanded a large cognitive effort. Also, I got frustrated many times because I thought I was all set up until I realised I forgot to install a particular tool.

Consistent environment

The way I now approach this is to automate my setup as much as I can so that every time I set up a new machine, my development environment will be consistent each time. In order to make this happen, I like to structure my environment setup with the following categories:

Tools
Access
Configuration

Tools

I like to go with an approach of running a single command and install everything I need at once. The operating system that I’ve been using is macOS but most of the things that I’ll mention here also applies for Linux. In terms of Windows, probably you will find an equivalent. What is important here is to stick to the concept of automation.

What I use to install the tools that I rely on is Homebrew and it is simple as that:

$ brew install git

The command above installs git, as an example.

You also can use brew to install macOS apps (i.e. browser, code editor, image visualisation, etc) via Homebrew Cask

$ brew install --cask firefox

When you install something via brew (a.k.a Homebrew), the software is now managed by it. Meaning that whenever you need to upgrade, reinstall or delete, you can do via homebrew as follows:

$ brew upgrade git

The good thing about this is that you can now dump all your software list you ever installed via brew into one file and that can be used to set up a whole new machine with a single command. You can achieve that with Homebrew Bundle.

Please follow the official documentation to install it properly.

Once you are all set, you can run the following command that will consolidate all the things you have installed into a file usually named Brewfile:

$ brew bundle dump --file=Brewfile

Then, the Brewfile will look like this:

tap "github/gh"
tap "homebrew/bundle"
tap "homebrew/cask"
tap "homebrew/cask-fonts"
tap "homebrew/cask-versions"
tap "homebrew/core"
tap "homebrew/services"
brew "git"
brew "go"
brew "make"
brew "neovim"
brew "tmux"
brew "unzip"
cask "buttercup"
cask "docker"
cask "firefox"

Now, imagine you do that now, save this file somewhere (i.e. cloud). When you receive a new machine or even format your current machine, you can run brew bundle to restore all the software that you used to have. See the command below:

$ brew bundle --file=homebrew/Brewfile

The above will install everything as if you were running brew install git, brew install go, etc.

Access

Now you have your stuff in place, there will be a “necessary” pain of authenticating with most of them (i.e. your cloud storage, your music app). The way I like to approach this is to get handy a password manager.

PS: I usually use brew cask to install mine so I don’t have to install it manually ever again

In case you don’t have a password manager, I’d consider downloading one now, here’s why.

A few options to consider:

Configuration

This category is pretty much to make sure once you are all set up, your tools are the way you left them before changing machines (or before you restored your current machine). I personally don’t bother too much about browser config because I have personal accounts that bring my config from the browser’s cloud, but editor configuration is something that is really close to my workflow and if I don’t see my editor or my terminal the way I remembered, I might have a Hard time trying to remember where things were before becoming productive.

About code editors, you might have seen around some GitHub repo called dotfiles. The reason for this name is because most of the configs are files that have . in front of its name (i.e. .gitconfig, .vim, .zshrc, .idea, etc).

So what most people do, they create a git repository somewhere (i.e. GitHub, GitLab, Bitbucket, etc) and consolidate all configs into one place so whenever you clone your repo (from a brand-new machine), you can run a couple of commands and have your original config in place.

In addition, you can also add customisable scripts to speed up your initial setting. As an example, VSCode is an editor that you can install a number of plugins to support your day-to-day development. So, although I’m not a heavy VSCode user, I use it sometimes and I have a few plugins that help during these occasions. So I came up with a script that will read all my current plugins and store them into a file so whenever I set up a new environment, the script will install all of these plugins so that when I open VSCode, the settings.json will contain all plugins that I used to have in my previous environment. That’s was pretty much inspired by Homebrew Bundle

Here’s a snippet:

#!/bin/bash

###
# Creates symbolic link from this dir into where vscode is installed
# then reads VSCodeExtensionsFile and install each extension one by one
###
bundle()
{
  # Creates symbolic link
  rm -rf ~/Library/Application\ Support/Code/User/settings.json || true
  ln -s `pwd`/vscode/settings.json ~/Library/Application\ Support/Code/User/settings.json

  # Install extensions
  while read extension; do
    code --install-extension $extension
  done < vscode/VSCodeExtensionsFile

  echo "Done."
}

###
# List vscode extensions and place into VSCodeExtensionsFile file
###
dump()
{
  extensions="vscode/VSCodeExtensionsFile"
  echo "Reading existing extensions from VSCode onto $extensions"
  echo ""

  code --list-extensions | tee $extensions

  echo "Done."
}

$*

— Edited on Wed 20 Jan

If you want to use the the script above, you can copy its content into your machine with the following steps:

Create a file on your /usr/local/bin so that you can execute from anywhere

$ touch /usr/local/bin/vs-code-bundler

Grant permission to the script to being executed

$ chmod +x /usr/local/bin/vs-code-bundler

Open the file we created and paste the script
Test the script

Run the command below to get your existing extensions and dump into a file.

$ vs-code-bundler dump

Then check the content of vscode/VSCodeExtensionsFile and see if it matches with your existing extensions:

$ cat vscode/VSCodeExtensionsFile

Save this file somewhere and next time you can run the bundle command to install everything if you need to:

$ vs-code-bundler bundle

Conclusion

If you read until now, thank you very much, I hope this article help you somehow or help someone you know!

I’ll share below my personal dotfiles where I apply most of the things I’ve discussed and feel free to copy & paste and make your own config according to what makes sense to you.

https://github.com/alabeduarte/dotfiles

If you have any questions or feedback, feel free to email me on alabeduarte@gmail.com.

A few shout outs to friends that helped me and inspired me to do this post:

TDD (Test-Driven Development) - My personal journey

Fri, 01 Jan 2021 14:00:00 GMT

What is TDD? TDD stands for Test-Driven Development and it is a Software Development’s process that was credited to Kent Beck. The idea consists of writing unit tests for your program, making them fail, then introducing the minimum amount of code that is enough to make the test pass, then you continue writing more tests according to your requirements at hand. By having tests in place, any change you do on your main code (let’s call it production code from now) can be checked against those tests and running them for every new change can be a way to get faster feedback, as an alternative to boot your application (whatever that is), run by each scenario and check if things are working as expected.

My journey

TDD (Test-Driven Development) is one of many techniques for developing software and this article aims to share my personal experience with it. I hope that I can clarify my thoughts on when I believe it can help and when I believe we should take a step back. I need to say that I found TDD pretty difficult and abstract at first. There will always be a space for discussion and that’s why other processes such as pair-programming and code review are extremely complementary to what I consider healthy software development processes. Let me give you some context before I start, so then you can understand better where I came from.

I’ve started reading about TDD on the internet and what helped me the most in my first steps were the articles from the Caelum website. I found really nice examples of how to do it at the time through their articles and further I found books which led me to the formal definitions written by Kent Beck. Then I joined ThoughtWorks in 2011 and there I believe it was a turning point for me. ThoughtWorks is famous for its revolutionary mindset (look for the agile manifesto), the Tech Radar publications and for caring about code quality. However, the reason I believe working there was so important was because of the people that I had a chance to work with at the time. They really encouraged me to challenge the current state of the code and how it could be improved. We also had a strong pair-programming culture which combined with writing tests, challenging code maintainability became pretty natural.

Why do I believe TDD is important?

Test-Driven Development enables refactoring.

As I mentioned above, having tests that exercise your code’s intention (function or method) opens room for refactoring the code with stronger confidence. You can move stuff around, you can rename things that express better what you are trying to do, you can add an argument to a function or you can remove them all. If after all of that you run your tests and they pass, chances are that you’ve done everything right! The opposite is true as well. If you change things and after running the tests some of them fail, it could be a sign that you’ve done something wrong and needs to be fixed. While refactoring the code, if you notice that one single change affects multiple tests, it could be a sign that the coupling between components is high or the scope of the change/refactor is big.

With time, I learned that TDD is not about testing first necessarily. The process of writing tests first, seeing them fail to then make them pass to be able to refactor really helps but the key factor to me was let the tests drive how I think so that my scope of changes can be expressed in the tests. I might want to refactor something, but if my scenarios are pretty small, I can postpone this decision for later.

Test-Driven Development favours design

TDD is all about letting your tests guide you about the problem you need to solve. It is pretty common to use the baby steps terminology here. Basically, you will start with really small and basic scenarios (for a given input, I expect this output). With that in mind, your code design should be simple enough to satisfy the requirements. Another aspect that can contribute to better design is that your test is the first consumer of your code. There you will call the function that you carefully named and thoroughly added certain arguments and you will see if that really expresses what you want to do. You may ask: “Should I really pass 4 arguments in here?” “Is this name good?” “Isn’t too complicated to set up the initial state for just testing if this does what it needs to do?” If the answer to this question doesn’t feel quite right, you can use this opportunity to change your code and look at your unit tests again and imagine: “how will someone call this code in real life? Is it easy to read?”.

Sometimes, “For a given input, I expect this output” is not possible. You could argue that it is not that simple as sometimes it is not easy to structure input and expected output. However, The fact that might not be possible all times doesn’t change the fact that you can always think about it and make it as an exercise. Challenge yourself often and see if this is really the case. If not, try breaking down your code into smaller components and then ask this question again.

Good code design is pretty subjective!

YES! That is it! If I’m coding all by myself I’m pretty sure I’ll understand it all and every decision will make sense until I have to explain to someone. That’s how pair programming and/or code review becomes crucial here. The process of doing TDD evolves empathy as well. I tend to think that we need to solve some problems right away, but often when I share my thoughts with someone I realise that I’m thinking too far ahead. Conversations like that can help you to avoid overengineering and make decisions prematurely. As we know by now, our tests are the first consumers of our code, so lean on that and discuss with your peers whether this is really a good design. Here are some questions that I often try to ask myself:

Is my code easy to maintain?
Is my code easy to change?
Is my code easy to read?
Is my code expressive enough?

TDD doesn’t mean bug-free code!

I’ve heard an argument before saying that if you’re doing TDD, your code shouldn’t have bugs. Well, I believe this is a bold statement. Of course, my code can have bugs. Test-Driven Development is a technique that requires discipline and experience. If I don’t follow the steps, for example, if I never see my tests failing, I can fall into the false positive trap. It is crucial to write a test, see it fail, then make it pass! The tests should also be reliable. Is part of the good design I mentioned above that our tests are also easy to read and maintain. They should be predictable and clean. If there are too many dependencies or setups, it could be a sign that my code is too coupled, therefore, it will be hard to maintain and false positives can be introduced. Besides, at this stage, you could argue if having tests is really adding value given the amount of setup that it might require if you come to that point.

There is another aspect to it, which is: we still can write tons of unit tests following all the rules, but with the wrong assumptions. If we don’t understand the problem we are trying to solve, we will end up having tests that will exercise something that doesn’t make sense with tests passing.

Tooling

In the previous sections, I’ve described techniques, beliefs and discipline. To make it stick and be pleasant, we need to have good tooling. The tests should be fast to run. It should be quicker to run a test than open the application (i.e. browser or mobile device) myself and test it out. While coding, it should be quick to trigger the tests as well. Nowadays, most programming languages’ ecosystems contain some tool where it watches your code and whenever you save a file, the tests relevant to that file will run. That is the sweet spot, in my opinion.

Final thoughts and when doing TDD doesn’t help

I believe that Test-Driven Development doesn’t help when we are not quite certain about what to do and what to expect. Sometimes, you might not be familiar with the language, framework or platform and you might need some time to play around with the available APIs and see what it is possible and what can be a constraint.

As the expected outcome might be unknown, having the development guided by tests can be extremely difficult since TDD is all about defining the expectations and figuring out how to meet them. So what usually works well for me is to do quick experiments, writing code with no tests at all, see what can be done, explore the limits of the tool/platform/API and then restart with TDD mindset using the experiments as a reference/documentation. After that, I can safely throw the experiment away and continue with the new code.

Of course, this might not work for everyone, but as I mentioned a few times, it is all about the exercise. If you try to do that, you might learn a thing or two and next time you will perform better. All I want is the short feedback and the ability to iterate over my understanding of the problem at hand often.

References

This Blog

Fri, 01 Jan 2021 13:00:00 GMT

I’ve had some opportunities to write technical blogs and documentation throughout my career (in the context of my day-to-day job) but I always deferred the moment to atually write my own stuff, my own experiences you know?

Now, I’m finally ready – I guess. The idea is document and share my learnings so that we (you, dear reader, and myself) can come back later and check things out.

I hope you enjoy the posts!

About me

Fri, 01 Jan 2021 12:00:00 GMT

Background

Software Engineer since 2007, my professional career has given me a great experience building applications in many different languages and domains spanning health, energy/oil/gas, media and retail. I am a quality-focused engineer with over 5 years of experience leading technical teams of 10+ including coaching and mentoring offshore teams.

I have a solid understanding of object-oriented programming and functional programming paradigms applied with extensive experience on test-driven development (TDD) and pair programming techniques. I have delivered production applications in many different languages and platforms including Go, Elixir, Ruby, Javascript/Typescript, Scala, Java, Android and iOS.

Values

I believe in transparency, servant leadership and constant — two-way — feedback. I’m constantly challenging user’s value and scope and I feel pretty excited about social impact. I also believe that people can do amazing things given the right opportunity, and I also believe that opportunities can be created.

I also enjoy speaking/attending conferences, coaching, sharing knowledge and contributing back to the software community.

Ways of working: I have led a number of programs on the path of continuous delivery, with a focus on technical capability uplift and the realisation of benefits including shorter cycle time of features released to end-users.

I consider myself an easy-going person. I tend to avoid challenging the status quo without building a rapport around the environment and I try to listen and learn how things work first.

I appreciate knowledge sharing, thoughtful code reviews and pair programming. I wouldn’t be so confident and happy about my career if I didn’t have the input from the people that I had the chance to work with.

I like to apply TDD whenever is possible and I try to keep my changes small. I also believe in discipline and code that favours the ability to refactor and good design. I understand that good design is subjective, so I tend to ask some key questions while I’m coding, such as:

Is my code easy to maintain?
Is my code easy to change?
Is my code easy to read?
Is my code expressive enough?

When doing code review, I tend to be flexible by encouraging follow-up PRs to address minor changes so that features can be unblocked as smaller PRs are being shipped. That also means a smaller scope of changes and fewer risks of breaking things.

RSS Feed

Context Engineering: How I've Been Using Claude Code in My Development Workflow

Building Context Through Dialogue

From Understanding to Planning

Iterative Planning and Documentation

Using Tests as Validation Checkpoints

Implementation with Precision

Conclusion

Retrospectives - Roles and Expectations

Formats

How the activity went out

First step: bullet points from Idea to Software lifecycle

Second step: fill out the “Roles and Expectations” matrix

No action items, for now…

Takeaways from this particular retro

Thank you for reading

Other References

The semantics of Marshalling in Go

What should we call this?

The term Marshalling

How Marshal/Unmarshal can be used in Go

Back to Marshalling and Unmarshalling

Converting from one format to another

Data format transformations (i.e. JSON, XML, etc)

Code examples

Converting from one domain to another

Final thoughts

Thank you for reading

References

3 approaches to consider when rendering conditional content in React

Use-case

New requirements

Approaches

1. Adding a new prop with boolean values

Pros

Cons

2. Adding a new prop with an enum

Pros

Cons

3. Using composition

Pros

Cons

Thank you for reading

Multiple .gitconfig files

What .gitconfig is for?

Getting started

Checking Your Settings

Dealing with multiple configurations

1. Create a new file:

2. Add the work-related info to the newly created file:

3. Add conditional config to the global Git config

Dealing with different signature keys

1. Create a new file with “personal” config:

2. Add the signature (i.e. in our case, the signature is SECRET) to the newly created file:

3. Add your work-related signature (i.e. SECRETWORK on this case) to your the work-related Git config

4. Now let’s configure our global ~/.gitconfig with the following:

5. All set!

Thank you for reading

Setting up a new machine

Dang! Got a new laptop and I have to set up everything… again…

Consistent environment

Tools

Access

Configuration

Conclusion

TDD (Test-Driven Development) - My personal journey

My journey

Why do I believe TDD is important?

Test-Driven Development enables refactoring.

Test-Driven Development favours design

Good code design is pretty subjective!

TDD doesn’t mean bug-free code!

Tooling

Final thoughts and when doing TDD doesn’t help

References

This Blog

About me

Background

Values

What `.gitconfig` is for?

4. Now let’s configure our global `~/.gitconfig` with the following: