This standard describes how a developer works with an AI coding agent (Claude Code) in a unified workspace. The goal is for the AI agent to generate code not from abstract descriptions, but from detailed specifications, ideally reviewed by the team lead.
Key principle: plan first, code second. The developer doesn't write code right away — they create a task specification, get it reviewed, and only then proceed to implementation.
Claude Code installation is described in a separate document.
All repositories are cloned inside claude_workspace:
| Repository | Hosting | Purpose |
|---|---|---|
| Product Repos | GitHub (WALTER-WRITES) | Source code of repositories such as: walter-backend, walter-developer-portal-microservice, app, AI-Humanizer, AI-Detector, walter-go-plugin |
| tech_docs | GitLab | Project documentation: architecture, API, data-flow, guides |
| context_base | GitLab | Tasks, specifications, blockers |
Clone the Product Repos you need (not necessarily all — only the ones you work with), tech_docs and context_base inside claude_workspace. Nested repositories are excluded via .gitignore — they don't interfere with each other.
No access to GitLab? Ask the CTO to create an account at https://gitlab.wdscode.guru, and ask your team lead to add you to the
waltergroup with the necessary permissions.
claude_workspace is not just a folder — it's a separate git repository with shared AI agent settings:
CLAUDE.md — global instructions (communication language, general rules).claude/settings.json — Claude Code settings (tool permissions, model).claude/skills/ — prompts for common operations, invoked via slash commands, for example:
/review-backend — backend code review: critical issues only (security, data loss, race conditions)/review-frontend — frontend code review (XSS, memory leaks, broken auth)/commit — staged changes → conventional commit messageSkills and settings are a living tool. The team is expected to improve them: add new skills for repetitive tasks, refine prompts of existing ones, configure CLAUDE.md and settings.json. If you notice you're giving the agent the same instruction repeatedly — that's a candidate for a new skill.
What to commit and what not to: Only shared settings are pushed to the repository — skills, tool permissions, general rules in
CLAUDE.md. Personal settings (e.g.,PREFERRED_LANGUAGE) are set locally by each developer and not committed — they are individual.
The AI agent works in the context of claude_workspace and sees everything simultaneously: product code, documentation, tasks. It can read real models from walter-backend, check the architecture in tech_docs, and create a plan in context_base — without switching between windows and without losing context.
context_base contains two main directories:
context_base/
teamwork_tasks/ — tasks and specifications for implementation
research/ — research (dev, ML, architectural)
Each task is a directory inside teamwork_tasks/:
teamwork_tasks/
<task-id-or-shortname>/
task.md — Business requirements, technical context, Definition of Done
subtask_{id}.md — Step-by-step implementation specification for a subtask
blocker_{id}.md — Description of an obstacle with context and steps taken
credentials.md — Access credentials for the task (in .gitignore, not committed). Using production credentials as AI context is prohibited, and committing them is also prohibited)
Directory naming:
44265321stripe-multi-account-plans, remove-downgradeFile naming:
subtask_001.md, subtask_002.md — numbering for sequential subtaskssubtask_TBD_celery-workers.md — descriptive name if there's no tracker IDsubtask_44257304.md — subtask ID from the trackerblocker_plan_details.md — descriptive name if there's no tracker IDblocker_44269810.md — blocker ID (also a subtask) from the trackerRules:
task.md is required. Without it, the task is not considered properly formedcredentials.md — always in .gitignore, contains only non-production credentialsA directory for research — from both the dev team and the ML team. Research differs from a task: it has no clear Definition of Done at the start; the goal is to investigate a topic and document findings.
research/
<topic-shortname>/
research.md — Goal, context, sequential research steps, conclusions
Structure of research.md:
Research examples:
research/credit-pricing-model/ — credit pricing analysis for humanizer/detectorresearch/stripe-multi-account/ — exploring Stripe multi-account options (Connect vs. separate keys)research/deberta-vs-roberta/ — model comparison for AI detectionProcess:
research.mdteamwork_tasks/ (if implementation is needed) or tech_docs is updated (if it's an architectural decision)Two layers:
generated/ — auto-generated documentation for products (WalterWrites, Proofademic, Dev Portal). Useful as a reference, but may contain inaccuraciesreviewed/ — verified and approved by the team. Examples:
reviewed/global/ — shared standards and processesreviewed/walterwrites/ — WalterWrites documentationWhen working on a task, the agent uses tech_docs as a reference. After completing a task, the developer updates the documentation (see Stage 5).
The AI agent sees everything in the workspace and everything passed to it as context. The following data is prohibited from being placed in the project or passed to the agent:
credentials.md (which is in .gitignore)Agent action control: It is prohibited to allow the agent to edit files and execute commands without user review and confirmation. Claude Code must operate in a mode where every action (file editing, command execution) requires explicit developer approval. Do not use automatic confirmation (--dangerously-skip-permissions) in work projects.
context_base/teamwork_tasks/task.md: business requirements, constraints, what you knowtech_docs for architectural contextsubtask_{id}.md for each subtaskblocker_{id}.mdcontext_base (branch or MR)The team lead checks:
task.md — is the task understood correctly, is the technical context accuratesubtask_{id}.md — is the plan adequate, are there missing edge cases, is it overcomplicatedblocker_{id}.md — are blockers justifiedProceeding to code — ideally after team lead approval (exceptions exist). Mistakes in specifications are cheaper to fix before writing code.
An approved subtask_{id}.md is a ready-made prompt for the AI agent. It contains: specific files, models, steps, completion criteria.
/review-backend or /review-frontend to find critical issuesIf stuck (unclear error, logic contradiction, lack of access):
blocker_{id}.md with AI — with enough context so the helper can understand without additional questionsAfter successful implementation and testing:
tech_docs based on accumulated context: API changes, new architectural decisions, guidesgenerated/, after review — to reviewed/tech_docs, close the task